Skip to main content

​
Overview

The kosh build command processes your content, templates, and assets to generate a complete static site. It features intelligent caching to skip unchanged files and supports watch mode for automatic rebuilds.

​
Usage

kosh build [flags]

​
Flags

​
--watch
boolean
default:"false"
Watch for file changes and automatically rebuild the site. Monitors content/, template directory, static directory, and kosh.yaml.
​
--cpuprofile
string
Write CPU profile to the specified file for performance analysis.
kosh build --cpuprofile cpu.prof
​
--memprofile
string
Write memory profile to the specified file for memory usage analysis.
kosh build --memprofile mem.prof
​
-baseurl
string
Override the base URL from kosh.yaml. Useful for building for different environments.
kosh build -baseurl https://example.com
​
-drafts
boolean
default:"false"
Include draft posts in the build. Posts marked with draft: true in frontmatter are normally excluded.
​
-theme
string
Override the theme specified in kosh.yaml.
kosh build -theme custom-theme

​
Examples

kosh build

​
Build Process

The build command executes in the following order:
  1. Setup & Validation
    • Acquires build lock to prevent concurrent builds
    • Validates configuration and paths
    • Checks for WASM updates
  2. Static Assets (must complete first)
    • Processes CSS, JavaScript, and images
    • Generates content-hashed filenames for cache busting
    • Populates the Assets map used by templates
  3. Content Processing
    • Parses Markdown files with frontmatter
    • Renders posts using templates
    • Generates search indexes with BM25 scoring
    • Creates social media cards
  4. Global Pages
    • Generates pagination pages
    • Renders tag pages
    • Creates 404 page
    • Builds knowledge graph visualization
  5. PWA Generation (if enabled)
    • Generates manifest.json
    • Creates service worker
    • Generates app icons
  6. Disk Synchronization
    • Syncs virtual filesystem to disk
    • Uses parallel worker pools for fast writes

​
Intelligent Caching

Kosh uses BLAKE3-based caching to skip rebuilding unchanged files:
  • Content Hash: Detects changes in Markdown source
  • Body Hash: Tracks content-only changes (v1.2.1+)
  • Template Tracking: Invalidates affected posts when templates change
  • Dependency Detection: Rebuilds when global dependencies change
  • Cache Rehydration: Restores from cache on template-only changes

​
Terminal Output

$ kosh build
📦 Building assets...
📝 Processing content...
   ✅ Content processed.
📄 Rendering pagination...
🏷️  Rendering tags...
🕸️  Rendering graph and metadata...
📱 Generating PWA...
💾 Syncing to disk...
📊 Built 42 posts in 1.2s (cache: 38/42 hits, 90.5%)

​
Performance Tips

  1. Use Watch Mode During Development: Incremental rebuilds are 5-10x faster than full builds
  2. Keep Cache Healthy: Run kosh cache gc periodically to remove orphaned data
  3. Profile Slow Builds: Use --cpuprofile to identify bottlenecks
  4. Minimize Global Dependencies: Changes to layout.html trigger full rebuilds

Build docs developers (and LLMs) love

Get started for freeTalk to us