Skip to main content

​
Overview

The kosh init command scaffolds a new Kosh static site with the essential directory structure, configuration file, and a starter post.

​
Usage

kosh init [name]

​
Arguments

​
name
string
Optional project name. If provided, creates the project in a subdirectory with that name. If omitted, initializes in the current directory.

​
What Gets Created

The init command creates the following structure: 
.
├── kosh.yaml          # Site configuration
├── content/           # Markdown source files
│   └── hello-world.md # First post with quickstart guide
├── themes/            # Theme directory (empty - install theme separately)
├── public/            # Build output (created but empty)
└── static/            # Static assets (created but empty)

​
Generated Files

​
kosh.yaml

A minimal configuration file with sensible defaults: 
# Site Configuration
title: "My Kosh Site"
description: "A new site built with Kosh"
baseURL: "http://localhost:2604"
language: "en"

author:
  name: "Author Name"
  url: "https://example.com"

# Navigation
menu:
  - name: "Home"
    url: "/"
  - name: "Tags"
    url: "/tags/index.html"

# Features
postsPerPage: 10
compressImages: true

# Theme Configuration
theme: "blog"
themeDir: "themes"
Source: internal/scaffold/scaffold.go:9-34

​
content/hello-world.md

A welcome post with instructions for installing a theme and running the dev server: 
---
title: "Hello World"
date: "2026-03-03"
tags: ["kosh", "welcome"]
draft: false
---

# Welcome to Kosh!

This is your first post. You can edit this file in `content/hello-world.md`.

## Getting Started

1.  **Themes**: Kosh requires a theme. Install the official blog theme:
    \`\`\`bash
    git clone https://github.com/Kush-Singh-26/kosh-theme-blog themes/blog
    \`\`\`

2.  **Run**: Start the dev server.
    \`\`\`bash
    kosh serve --dev
    \`\`\`
Source: internal/scaffold/scaffold.go:36-70

​
Behavior

If kosh.yaml already exists in the target directory, the init command skips creating it and prints a warning:
⚠️ 'kosh.yaml' already exists, skipping.
This prevents accidentally overwriting your configuration.
If the first post already exists, it is skipped silently to avoid overwriting your content.
All directories are created with 0755 permissions (rwxr-xr-x), ensuring the owner has full access and others can read and execute.

​
Examples

​
Initialize in Current Directory

kosh init
Output: 
🌱 Initializing new Kosh project...
   📁 Created 'content/'
   📁 Created 'themes/'
   📁 Created 'public/'
   📁 Created 'static/'
   📄 Created 'kosh.yaml'
   📝 Created 'content/hello-world.md'

✅ Project initialized successfully!
   👉 Clone a theme into 'themes/' to get started.

​
Initialize with Project Name

kosh init my-blog
cd my-blog
Creates a new my-blog/ directory with the full project structure.

​
Next Steps

After running kosh init, you need to install a theme before building:
1

Install a Theme

Clone the official blog theme:
git clone https://github.com/Kush-Singh-26/kosh-theme-blog themes/blog
Or the docs theme:
git clone https://github.com/Kush-Singh-26/kosh-theme-docs themes/docs
2

Start Development Server

kosh serve --dev
This builds your site and starts a server at http://localhost:2604 with live reload.
3

Customize Configuration

Edit kosh.yaml to set your site title, author, navigation, and features.

​
Source Code

Implementation: internal/scaffold/scaffold.go:73-115

Build docs developers (and LLMs) love

Get started for freeTalk to us