Configuration Reference

Kosh is configured via a kosh.yaml file in your project root. This file controls site metadata, build behavior, theme settings, and feature toggles.

Example Configuration

kosh.yaml

# Site Configuration
title: "Kush Blogs"
description: "I write about machine learning, deep learning and lately more about NLP."
logo: "static/images/kush3.png"
baseURL: "" # Empty for local dev, override via CLI flag
language: "en"

# Author
author:
  name: "Kush Singh"
  url: "https://kush-singh-26.github.io/"

# Navigation
menu:
  - name: "Search"
    id: "search-btn"
    class: "nav-btn"
  - name: "Tags"
    url: "/tags/index.html"
  - name: "Graph"
    url: "/graph.html"
  - name: "Home"
    url: "https://kush-singh-26.github.io/"
    target: "_blank"
  - name: "GitHub"
    url: "https://github.com/Kush-Singh-26/blogs"
    target: "_blank"

# Global Features & Generators
features:
  rawMarkdown: true
  generators:
    sitemap: true
    rss: true
    graph: true
    pwa: true
    search: true

# Social Cards (Open Graph Images)
socialCards:
  background: "#faf8f5"
  gradient:
    - "#e8e0d0"
    - "#c9b896"
    - "#b8a078"
  angle: 135
  textColor: "#1a1a1a"

# Build Optimization
postsPerPage: 10
compressImages: true
imageWorkers: 24

# Theme Configuration
theme: "blog"
themeDir: "themes"
templateDir: "themes/blog/templates"
staticDir: "themes/blog/static"

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

Site Metadata

title

string

required

Site title displayed in <title> tags, navigation, and RSS feed.

title: "My Tech Blog"

description

string

required

Site description used in meta tags and RSS feed.

description: "Thoughts on software engineering and cloud architecture"

baseURL

string

default:""

Base URL for absolute links (sitemap, RSS, canonical URLs). Leave empty for local development.Auto-detection: If empty and running serve --dev, auto-detects as http://localhost:2604.Override: Use -baseurl flag for deployment:

kosh build -baseurl https://example.com

baseURL: "https://myblog.com"

language

string

default:"en"

Site language code for <html lang> attribute.

language: "en"

logo

string

Path to site logo/favicon. Used for:

Browser favicon
PWA icons (auto-resized)
Social card branding

Supports: PNG, JPG, WebP

logo: "static/images/logo.png"

Author Information

author

object

Author metadata displayed in templates and RSS feed.

author:
  name: "Jane Doe"
  url: "https://janedoe.com"

Properties:

name (string, required) - Author’s full name
url (string, optional) - Author’s website or profile URL

Navigation menu items rendered in site header.

menu:
  - name: "Home"
    url: "/"
  - name: "About"
    url: "/about.html"
  - name: "GitHub"
    url: "https://github.com/username"
    target: "_blank"
  - name: "Search"
    id: "search-btn"
    class: "nav-btn"

Properties per item:

name (string, required) - Display text
url (string, optional) - Link URL (omit for button-only items)
target (string, optional) - Link target (_blank for new tab)
id (string, optional) - HTML element ID for JS hooks
class (string, optional) - CSS class names

Directory Paths

contentDir

string

default:"content"

Directory containing markdown source files. Supports relative or absolute paths.

contentDir: "content"

outputDir

string

default:"public"

Build output directory. Supports relative or absolute paths.Use Case: Hugo-style integration with existing sites.

# Relative to project root
outputDir: "../portfolio/blogs"

# Absolute path
outputDir: "/var/www/myblog"

cacheDir

string

default:".kosh-cache"

BoltDB cache directory for incremental builds.

cacheDir: ".kosh-cache"

Note: This directory should be added to .gitignore but preserved in CI for faster builds.

Theme System

theme

string

default:"blog"

required

Theme name. Must match a directory in themeDir.

theme: "blog"

Available Themes:

blog - Personal blog theme (kosh-theme-blog)
docs - Documentation theme with versioning (kosh-theme-docs)

themeDir

string

default:"themes"

Parent directory containing theme subdirectories.

themeDir: "themes"

Structure:

themes/
├── blog/
│   ├── templates/
│   └── static/
└── docs/
    ├── templates/
    └── static/

templateDir

string

Override template directory. Defaults to themes/<theme>/templates.

templateDir: "themes/blog/templates"

staticDir

string

Override static assets directory. Defaults to themes/<theme>/static.

staticDir: "themes/blog/static"

Features & Generators

features

object

Enable or disable global features and content generators.

features:
  rawMarkdown: true
  generators:
    sitemap: true
    rss: true
    graph: true
    pwa: true
    search: true

features.rawMarkdown

boolean

default:false

Deploy .md files alongside .html for “View Source” functionality.

features:
  rawMarkdown: true

features.generators.sitemap

boolean

default:true

Generate sitemap.xml for search engines.

features:
  generators:
    sitemap: true

features.generators.rss

boolean

default:true

Generate rss.xml feed.

features:
  generators:
    rss: true

features.generators.graph

boolean

default:true

Generate knowledge graph visualization (graph.html) showing post-tag relationships.

features:
  generators:
    graph: true

features.generators.pwa

boolean

default:true

Generate PWA files (manifest, service worker, icons). Skipped in serve --dev mode.

features:
  generators:
    pwa: true

features.generators.search

boolean

default:true

Build WASM search index with BM25 scoring, fuzzy matching, and stemming.

features:
  generators:
    search: true

Build Optimization

postsPerPage

number

default:10

Number of posts per page for index pagination.

postsPerPage: 15

compressImages

boolean

default:true

Automatically convert PNG/JPG to optimized WebP. Highly recommended for performance.

compressImages: true

imageWorkers

number

default:24

Number of parallel workers for image compression. Min: 1, Max: 32.

imageWorkers: 24

Tuning:

Low-end machines: imageWorkers: 4
High-end machines: imageWorkers: 32

Configuration for auto-generated Open Graph images.

socialCards:
  background: "#faf8f5"
  gradient:
    - "#e8e0d0"
    - "#c9b896"
    - "#b8a078"
  angle: 135
  textColor: "#1a1a1a"

Base background color (hex or named).

socialCards:
  background: "#ffffff"

Array of gradient color stops (hex or named). Renders as linear gradient.

socialCards:
  gradient:
    - "#667eea"
    - "#764ba2"

Gradient angle in degrees (0-360).

socialCards:
  angle: 45 # Diagonal gradient

Text color for title and description.

socialCards:
  textColor: "#ffffff"

Versioning (Docs Theme)

versions

array

Documentation versions for the docs theme. Each version gets its own URL namespace.

versions:
  - name: "v4.0 (latest)"
    path: "v4.0"
    isLatest: true
  - name: "v3.0"
    path: "v3.0"
    isLatest: false
  - name: "v2.0"
    path: "v2.0"
    isLatest: false

Properties per version:

name (string, required) - Display name in version selector
path (string, required) - URL path segment (e.g., v4.0)
isLatest (boolean, required) - Mark as latest version

URL Structure:

/getting-started.html         → Latest version
/v4.0/getting-started.html    → Latest version (dual access)
/v3.0/getting-started.html    → v3.0 version

Creating New Versions:

kosh version v5.0

Configuration Best Practices

Development vs. Production

Development:

baseURL: "" # Auto-detects http://localhost:2604
compressImages: true
features:
  generators:
    pwa: true # Skipped in --dev mode anyway

Production:

kosh build -baseurl https://myblog.com

GitHub Pages

baseURL: "" # Override via CI
outputDir: "public"
theme: "blog"
features:
  generators:
    sitemap: true
    rss: true
    pwa: true

CI Workflow:

- name: Build
  run: kosh build -baseurl https://username.github.io/repo

Hugo-Style Integration

Integrate Kosh into existing sites:

outputDir: "../portfolio/blogs"
baseURL: "https://myportfolio.com/blogs"

File Structure:

myportfolio.github.io/
├── index.html          # Portfolio homepage
├── css/
├── js/
└── blogs-src/          # Kosh project
    ├── kosh.yaml       # outputDir: "../blogs"
    └── content/
└── blogs/              # Generated output

Performance Tuning

For large sites (>500 posts):

imageWorkers: 32        # Max parallel workers
postsPerPage: 20        # Reduce total pages
compressImages: true    # Essential for performance

Minimal Configuration

Smallest viable kosh.yaml:

title: "My Blog"
description: "A simple blog"
theme: "blog"

Environment-Specific Overrides

While Kosh doesn’t natively support multiple config files, you can use shell scripting:

# dev.sh
kosh serve --dev -baseurl http://localhost:2604

# prod.sh
kosh build -baseurl https://myblog.com

Or use YAML anchors for shared config:

kosh.yaml

defaults: &defaults
  title: "My Blog"
  theme: "blog"
  postsPerPage: 10

<<: *defaults
baseURL: "https://myblog.com"

Validation

Kosh validates configuration at startup:

Theme directory must exist at themes/<theme>/
templates/ directory is required
imageWorkers capped at 32
Version paths must be unique

Error Example:

❌ Theme not found: themes/missing/
   Install theme: git clone <repo> themes/missing

Get Started

Core Concepts

Usage

Features

Development

Configuration Reference

Configuration Reference

Example Configuration

Site Metadata

Author Information

Navigation Menu

Directory Paths

Theme System

Features & Generators

Build Optimization

Versioning (Docs Theme)

Development vs. Production

GitHub Pages

Hugo-Style Integration

Performance Tuning

Minimal Configuration

Environment-Specific Overrides

Validation

Build docs developers (and LLMs) love

Get Started

Core Concepts

Usage

Features

Development

​Configuration Reference

​Example Configuration

​Site Metadata

​Author Information

​Navigation Menu

​Directory Paths

​Theme System

​Features & Generators

​Build Optimization

​Social Cards

​Versioning (Docs Theme)

​Development vs. Production

​GitHub Pages

​Hugo-Style Integration

​Performance Tuning

​Minimal Configuration

​Environment-Specific Overrides

​Validation

Build docs developers (and LLMs) love

Configuration Reference

Example Configuration

Site Metadata

Author Information

Navigation Menu

Directory Paths

Theme System

Features & Generators

Build Optimization

Social Cards

Versioning (Docs Theme)

Development vs. Production

GitHub Pages

Hugo-Style Integration

Performance Tuning

Minimal Configuration

Environment-Specific Overrides

Validation