Quickstart Guide

Get your Kosh static site up and running in minutes. This guide takes you from zero to a fully deployed site with live reload, search, and CI/CD.

Prerequisites

Go 1.23+ installed (download here)
Git for theme installation
A text editor (VS Code, Vim, etc.)

Installation & Setup

<Steps> <Step title=“Install Kosh”> Install the Kosh CLI via go install: <CodeGroup>

macOS/Linux

go install github.com/Kush-Singh-26/kosh/cmd/kosh@latest

# Verify installation
kosh version

Windows

go install github.com/Kush-Singh-26/kosh/cmd/kosh@latest

# Verify installation
kosh version

</CodeGroup> <Note> Ensure $GOPATH/bin (Linux/macOS) or %USERPROFILE%\go\bin (Windows) is in your PATH. </Note> </Step> <Step title=“Initialize Your Site”> Create a new Kosh project with the default directory structure:

kosh init my-blog
cd my-blog

This creates:

my-blog/
├── content/          # Your markdown posts go here
├── static/           # Images, fonts, custom CSS/JS
│   └── images/
├── themes/           # Theme files (install next)
└── kosh.yaml         # Site configuration

</Step> <Step title=“Install a Theme”> Kosh uses detachable themes. Install the official blog theme: <CodeGroup>

Blog Theme

git clone https://github.com/Kush-Singh-26/kosh-theme-blog themes/blog

Docs Theme

git clone https://github.com/Kush-Singh-26/kosh-theme-docs themes/docs

</CodeGroup> Update kosh.yaml to use your chosen theme:

kosh.yaml

theme: "blog"  # or "docs"
themeDir: "themes"

<Note> The blog theme is for articles with tags and pagination. The docs theme supports versioning, search, and structured navigation. </Note> </Step> <Step title=“Configure Your Site”> Edit kosh.yaml with your site details:

kosh.yaml

# Site Configuration
title: "My Blog"
description: "Thoughts on software, ML, and life"
logo: "static/images/logo.png"
baseURL: "https://yourusername.github.io/my-blog"
language: "en"

# Author
author:
  name: "Your Name"
  url: "https://yourwebsite.com"

# Navigation
menu:
  - name: "Home"
    url: "/"
  - name: "Tags"
    url: "/tags/index.html"
  - name: "GitHub"
    url: "https://github.com/yourusername"
    target: "_blank"

# Global Features
features:
  rawMarkdown: true      # Deploy .md alongside .html
  generators:
    sitemap: true        # SEO sitemap.xml
    rss: true            # RSS feed
    graph: true          # Knowledge graph
    pwa: true            # Progressive Web App
    search: true         # WASM full-text search

# Build Settings
postsPerPage: 10
compressImages: true     # Auto-convert to WebP

# Theme
theme: "blog"
themeDir: "themes"

# Directories (defaults shown)
contentDir: "content"
outputDir: "public"
cacheDir: ".kosh-cache"

<Note> Leave baseURL empty for local development—it auto-detects http://localhost:2604. Override with -baseurl flag in production. </Note> </Step> <Step title=“Create Your First Post”> Generate a new blog post with frontmatter:

kosh new "My First Post"

This creates content/my-first-post.md:

content/my-first-post.md

---
title: "My First Post"
description: "An introduction to my new blog"
date: "2026-03-03"
tags: ["blogging", "kosh"]
draft: false
---

Welcome to my blog! This is my first post built with Kosh.

## Features I Love

- **Blazing fast** incremental builds with BoltDB caching
- **Live reload** during development
- **LaTeX** and **D2 diagrams** rendered server-side as SVG
- **Full-text search** powered by WebAssembly

Check out the [official docs](https://github.com/Kush-Singh-26/kosh) for more!

Frontmatter Reference

Field	Type	Description
`title`	string	Post title (required)
`description`	string	Meta description for SEO
`date`	string	Publication date (YYYY-MM-DD)
`tags`	array	Tags for categorization
`draft`	boolean	Exclude from builds if `true`
`pinned`	boolean	Pin to top of homepage
`weight`	number	Sort order (higher = first)
`image`	string	Custom social card image
</Step>

<Step title=“Start Development Server”> Launch the dev server with live reload:

kosh serve --dev

🚀 Serving on http://localhost:2604
📁 Watching: content/, themes/, static/
🔄 Auto-reload enabled

Open http://localhost:2604 in your browser. Edits to markdown, templates, or CSS trigger instant rebuilds. <CodeGroup>

Include Drafts

kosh serve --dev -drafts

Custom Port

kosh serve --dev --port 8080

Custom Host

kosh serve --dev --host 0.0.0.0 --port 3000

</CodeGroup> </Step> </Steps>

Project Structure

After initialization and theme installation, your project looks like this:

my-blog/
├── content/
│   ├── my-first-post.md
│   └── another-post.md
├── static/
│   ├── images/
│   │   └── logo.png
│   └── custom.css            # Optional overrides
├── themes/
│   └── blog/
│       ├── templates/
│       │   ├── layout.html   # Base template
│       │   ├── index.html    # Homepage
│       │   ├── post.html     # Single post
│       │   └── 404.html
│       ├── static/
│       │   ├── css/
│       │   └── js/
│       └── theme.yaml
├── public/                   # Build output (generated)
├── .kosh-cache/              # Build cache (generated)
└── kosh.yaml                 # Site config

Common Workflows

Create a New Post

kosh new "Understanding Transformers"

Frontmatter Examples

Blog Post:

---
title: "Understanding Transformers"
description: "Deep dive into attention mechanisms"
date: "2026-03-03"
tags: ["AI", "NLP", "Transformers"]
pinned: false
draft: false
---

Documentation Page (with weight):

---
title: "API Reference"
description: "Complete API documentation"
date: "2026-03-03"
weight: 10  # Higher = appears first
draft: false
---

Markdown Extensions

Kosh supports:

Admonitions: :::info, :::warning, :::danger, :::note
Syntax Highlighting: Fenced code blocks with language tags
LaTeX Math: Inline $E = mc^2$ and block $$...$$
D2 Diagrams: Fenced blocks with d2 language tag
Tables: GitHub-flavored markdown tables
Task Lists: - [ ] and - [x]

LaTeX Example

Inline math: $\sum_{i=1}^n x_i$

Block equation:
$$
\frac{\partial L}{\partial w} = 2(y - \hat{y}) \cdot x
$$

D2 Diagram Example

```d2
client -> server: HTTP Request
server -> database: Query
database -> server: Results
server -> client: JSON Response
```

</Accordion> <Accordion title=“Development Workflow” icon=“code”>

Live Development

Start the dev server and edit files in real-time:

kosh serve --dev

Changes to these directories trigger auto-reload:

content/ - Markdown posts
themes/ - Templates and theme assets
static/ - Static files
templates/ - Custom templates (if not using theme)

Performance Tips

Incremental builds: Only changed files rebuild (~100ms)
Cache hits: ~95% on typical edits (BoltDB persistent cache)
Parallel processing: 24 concurrent image workers by default

Development Flags

Flag	Description
`--dev`	Enable watch mode + live reload
`-drafts`	Include `draft: true` posts
`--port 8080`	Change server port
`--host 0.0.0.0`	Bind to all interfaces
</Accordion>

Build for Production

kosh build -baseurl https://yourdomain.com

This generates:

Minified HTML, CSS, JS
Optimized WebP images
sitemap.xml for SEO
rss.xml feed
search.bin (WASM search index)
Service worker (if PWA enabled)
Social card images (Open Graph)

Build Output

public/
├── index.html
├── posts/
│   ├── my-first-post.html
│   └── my-first-post.md      # Raw markdown (if rawMarkdown: true)
├── tags/
│   └── index.html
├── static/
│   ├── css/
│   │   └── layout-a3f2b1.css  # Content-hashed filenames
│   ├── js/
│   ├── images/
│   └── wasm/
│       └── search.wasm
├── sitemap.xml
├── rss.xml
├── search.bin                  # Msgpack-encoded search index
└── manifest.json               # PWA manifest

Build Flags

# Override base URL
kosh build -baseurl https://custom.com

# Include drafts
kosh build -drafts

# Use different theme
kosh build -theme docs

# Profile build performance
kosh build --cpuprofile cpu.prof --memprofile mem.prof

Clean Build Artifacts

# Clean output directory (preserves version folders)
kosh clean

# Clean output + cache (force full rebuild)
kosh clean --cache

# Clean everything including all versions
kosh clean --all --cache

</Accordion> <Accordion title=“Cache Management” icon=“database”> Kosh uses BoltDB for persistent caching with BLAKE3 content addressing.

Cache Commands

# View cache statistics
kosh cache stats

Cache Statistics:
Posts: 42
HTML Artifacts: 38 (4 inline)
Total Size: 2.4 MB
Cache Hit Rate: 94.3%

Cache Operations

Command	Description
`kosh cache stats`	Show cache metrics
`kosh cache gc`	Run garbage collection
`kosh cache verify`	Check integrity
`kosh cache rebuild`	Clear for full rebuild
`kosh cache clear`	Delete all cache data
`kosh cache inspect <path>`	Show entry details

Garbage Collection

# See what would be deleted
kosh cache gc --dry-run

# Run GC (removes orphaned artifacts)
kosh cache gc

When to Clear Cache

After upgrading Kosh versions
When seeing stale content
Before profiling build performance
When cache size grows excessive

Cache Optimization

Inline HTML: Posts < 32KB stored inline (faster lookups)
Body hash tracking: Detects changes to post content only
LRU cache: Hot PostMeta cached in-memory (5-minute TTL)
Cross-platform: Normalized paths work on Windows/Linux/macOS </Accordion>

</AccordionGroup>

Deploy to GitHub Pages

<Steps> <Step title=“Create GitHub Repository”> Initialize a Git repository and push to GitHub:

git init
git add .
git commit -m "Initial commit"
git branch -M main
git remote add origin https://github.com/yourusername/my-blog.git
git push -u origin main

</Step> <Step title=“Add Deployment Workflow”> Create .github/workflows/deploy.yml:

.github/workflows/deploy.yml

name: Deploy to GitHub Pages

on:
  push:
    branches: ["main"]
  workflow_dispatch:

permissions:
  contents: read
  pages: write
  id-token: write

concurrency:
  group: "pages"
  cancel-in-progress: false

env:
  GO_VERSION: '1.23'

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Set up Go
        uses: actions/setup-go@v5
        with:
          go-version: ${{ env.GO_VERSION }}

      - name: Install Kosh
        run: go install github.com/Kush-Singh-26/kosh/cmd/kosh@latest

      - name: Restore File Timestamps
        uses: chetan/git-restore-mtime-action@v2

      - name: Restore Build Cache
        uses: actions/cache@v4
        with:
          path: .kosh-cache
          key: kosh-cache-${{ runner.os }}-${{ github.sha }}
          restore-keys: kosh-cache-${{ runner.os }}-

      - name: Build Static Site
        run: kosh build -baseurl https://${{ github.repository_owner }}.github.io/${{ github.event.repository.name }}

      - name: Setup Pages
        uses: actions/configure-pages@v5

      - name: Upload Artifact
        uses: actions/upload-pages-artifact@v3
        with:
          path: ./public

  deploy:
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
    needs: build
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4

</Step> <Step title=“Enable GitHub Pages”>

Go to repository Settings > Pages
Under Source, select GitHub Actions
Push to main branch to trigger deployment

Your site will be live at:

https://yourusername.github.io/my-blog

</Step> </Steps>

Custom Domain

To use a custom domain, add a CNAME file to static/:

static/CNAME

yourdomain.com

Update kosh.yaml:

baseURL: "https://yourdomain.com"

Performance Tips

Build Performance

Optimization	Impact	Description
Incremental builds	~100ms	Only changed files rebuild
BoltDB cache	95% hit rate	Persistent metadata cache
Parallel workers	24 concurrent	Image conversion parallelized
Content hashing	BLAKE3	Fast, cryptographically secure
Inline HTML	No disk I/O	Posts < 32KB stored inline

Runtime Performance

WASM Search: Client-side full-text search (no backend)
Service Worker: Stale-while-revalidate caching
Asset Fingerprinting: layout-a3f2b1.css enables infinite cache TTL
WebP Images: ~30% smaller than PNG/JPG
Minified Assets: HTML/CSS/JS optimized for production

Benchmarking

# Profile CPU usage
kosh build --cpuprofile cpu.prof

# Profile memory allocation
kosh build --memprofile mem.prof

# Analyze profiles
go tool pprof cpu.prof
go tool pprof mem.prof

Next Steps

Configuration Reference

Explore all kosh.yaml options, theme settings, and feature flags

Feature Documentation

Learn about WASM search, incremental builds, and asset pipeline

Theme Development

Create custom themes with Go templates and detachable architecture

Advanced Features

Versioning, native rendering, and performance optimization

Troubleshooting

Common Issues

“kosh: command not found”

Ensure $GOPATH/bin is in your PATH
Run go env GOPATH to find your Go path
Add export PATH=$PATH:$(go env GOPATH)/bin to .bashrc or .zshrc

Theme not found

Verify theme exists at themes/blog/ or themes/docs/
Check theme: "blog" matches directory name in kosh.yaml
Run git clone https://github.com/Kush-Singh-26/kosh-theme-blog themes/blog

Stale content after edits

Clear cache: kosh clean --cache
Verify file watcher is running in dev mode
Check frontmatter draft: false

Build errors in CI

Ensure Go 1.23+ in workflow: go-version: '1.23'
Verify cache restoration step
Check -baseurl flag format

Getting Help

GitHub Issues: Kush-Singh-26/kosh
Documentation: README.md
Examples: See test-site/ in the repository

Get Started

Core Concepts

Usage

Features

Development

​Prerequisites

​Installation & Setup

​Frontmatter Reference

​Project Structure

​Common Workflows

​Create a New Post

​Frontmatter Examples

​Markdown Extensions

​LaTeX Example

​D2 Diagram Example

​Live Development

​Performance Tips

​Development Flags

​Build for Production

​Build Output

​Build Flags

​Clean Build Artifacts

​Cache Commands

​Cache Operations

​Garbage Collection

​When to Clear Cache

​Cache Optimization

​Deploy to GitHub Pages

​Custom Domain

​Performance Tips

​Build Performance

​Runtime Performance

​Benchmarking

​Next Steps

Configuration Reference

Feature Documentation

Theme Development

Advanced Features

​Troubleshooting

​Common Issues

​Getting Help

Build docs developers (and LLMs) love

Prerequisites

Installation & Setup

Frontmatter Reference

Project Structure

Common Workflows

Create a New Post

Frontmatter Examples

Markdown Extensions

LaTeX Example

D2 Diagram Example

Live Development

Performance Tips

Development Flags

Build for Production

Build Output

Build Flags

Clean Build Artifacts

Cache Commands

Cache Operations

Garbage Collection

When to Clear Cache

Cache Optimization

Deploy to GitHub Pages

Custom Domain

Performance Tips

Build Performance

Runtime Performance

Benchmarking

Next Steps

Troubleshooting

Common Issues

Getting Help