Skip to main content

​
Overview

The kosh version commands manage documentation versioning for docs-style sites. Create frozen snapshots of your documentation and maintain multiple versions side-by-side.

​
Usage

kosh version [version-name]
kosh version [flags]

​
Commands

​
Show Current Versions

Display all configured versions and identify the current working version. 
kosh version

$ kosh version
📚 Version Information
======================
→  1. v3.0 - v3.0 [LATEST]
   2. v2.0 - v2.0
   3. v1.0 - v1.0

💡 Current working version: v3.0
   Edit files in content/ to update this version
Output Explained:
  • → Arrow marks the latest version
  • [LATEST] badge indicates the current working version
  • Version name shown with its path in the output directory

​
Create New Version

Freeze the current latest version and start a new working version. 
kosh version <vX.X>

$ kosh version v4.0
📸 Freezing version v3.0 to content/v3.0/...
📝 Updating version configuration...

✅ Version transition complete!
   Previous latest: v3.0 (content/v3.0/) → frozen
   New working version: v4.0 (content/v4.0/)
   Config updated with proper version ordering

​
Show Build Information

Display Kosh version and optimization features. 
kosh version --info

$ kosh version --info
Kosh Static Site Generator
Version: v1.2.0
Go Version: go1.23.5
Build Date: 2026-02-16

Optimized with:
  - BLAKE3 hashing (replaced MD5)
  - Object pooling for memory management
  - Pre-computed search indexes
  - Generic cache operations

​
Versioning Strategies

Kosh supports two versioning approaches:

​
All-in-Folders Style

All versions, including latest, live in folders:
kosh.yaml
versions:
  - name: v3.0
    path: v3.0
    isLatest: true
  - name: v2.0
    path: v2.0
    isLatest: false
Directory Structure: 
content/
├── v3.0/          # Latest (working version)
│   ├── index.md
│   └── getting-started.md
└── v2.0/          # Frozen
    ├── index.md
    └── quickstart.md
Creating New Version: 
kosh version v4.0
  • Marks v3.0 as frozen (isLatest: false)
  • Creates new content/v4.0/ folder (copies from v3.0)
  • Sets v4.0 as latest

​
Traditional Style (Root Latest)

Latest version at root, old versions in folders:
kosh.yaml
versions:
  - name: v3.0
    path: ""           # Empty path = root
    isLatest: true
  - name: v2.0
    path: v2.0
    isLatest: false
Directory Structure: 
content/
├── index.md               # Latest (v3.0)
├── getting-started.md     # Latest (v3.0)
└── v2.0/                  # Frozen
    ├── index.md
    └── quickstart.md
Creating New Version: 
kosh version v4.0
  • Copies root content to content/v3.0/
  • Updates v3.0 config: path: v3.0, isLatest: false
  • Creates new v4.0 entry: path: "", isLatest: true

​
Version Creation Process

When you run kosh version v4.0:
  1. Validation
    • Check if version name already exists
    • Verify a latest version exists
    • Detect versioning strategy from config
  2. Content Snapshot
    • All-in-folders: Copy content/v3.0/ → content/v4.0/
    • Traditional: Copy content/ → content/v3.0/
    • Only .md files are copied
    • Version folders are excluded from snapshot
  3. Config Update
    • Mark old latest as frozen (isLatest: false)
    • Add new version at top of list
    • Preserve YAML formatting and comments
    • Update path fields based on strategy
  4. Directory Handling
    • Existing unregistered directories trigger backup warning
    • Conflicts abort the operation
    • Creates parent directories as needed

​
Version URLs

After building, versions are accessible at: 
/                       # Hub page (docs theme)
/getting-started.html   # Latest version (dual access)
/v4.0/                  # Latest version landing
/v4.0/getting-started.html
/v3.0/                  # v3.0 landing
/v3.0/getting-started.html
/v2.0/                  # v2.0 landing
Version Selector: Dropdown in docs theme preserves current page path when switching versions.

​
Cleaning Behavior

The kosh clean command respects versioning: 
# Preserves version folders
kosh clean

# Removes all versions
kosh clean --all

​
Error Handling

​
Directory Exists

If the target directory exists but isn’t registered: 
⚠️  Warning: Directory 'content/v3.0' exists but is not registered. Renaming to backup...
   Backup created at: content/v3.0.backup

​
Directory Conflicts

If a registered version’s directory exists: 
❌ Error: Directory 'content/v3.0' already exists and is registered as a version

​
Config Errors

Can’t load config: 
❌ Error: Could not load kosh.yaml
No latest version: 
❌ Error: No current 'latest' version found in config
Duplicate version: 
❌ Error: Version 'v3.0' already exists in kosh.yaml

​
Version Metadata

Posts can access their version in frontmatter:
content/v2.0/getting-started.md
---
title: Getting Started
version: v2.0
---
The version field is automatically set during build based on the post’s location.

​
Best Practices

​
Version Naming

Use semantic versioning:
  • v1.0, v2.0, v3.0 - Major versions
  • v2.1, v2.2 - Minor versions (if needed)

​
When to Version

Create a new version when:
  • Making breaking API changes
  • Restructuring documentation significantly
  • Releasing a major product update
Don’t version for:
  • Minor content updates
  • Typo fixes
  • New pages that apply to all versions

​
Sparse Versioning

Only copy files that differ between versions. Use symlinks or theme logic to fall back to latest for unchanged content.

​
Migration Checklist

# 1. Verify current state
kosh version

# 2. Commit current work
git add -A
git commit -m "Finalize v3.0 docs"

# 3. Create new version
kosh version v4.0

# 4. Build and test
kosh build
kosh serve

# 5. Update version-specific content
vim content/v4.0/index.md

# 6. Commit version transition
git add -A
git commit -m "Start v4.0 documentation"

Build docs developers (and LLMs) love

Get started for freeTalk to us