Skip to main content

​
Overview

The kosh new command creates a new Markdown file in the content/ directory with pre-filled frontmatter and a basic structure. The filename is automatically generated from the post title.

​
Usage

kosh new "<title>"

​
Arguments

​
title
string
required
The title of your new post. Used for both the frontmatter title and to generate a URL-safe filename slug.

​
Examples

kosh new "My First Post"
# Creates: content/my-first-post.md

​
Slug Generation

The command converts your title into a safe filename using these rules:
  1. Lowercase: All characters converted to lowercase
  2. Spaces to Hyphens: Spaces replaced with -
  3. Remove Unsafe Characters: Characters like <>:"/\|?* and control characters removed
  4. Collapse Hyphens: Consecutive hyphens reduced to single hyphen
  5. Trim Hyphens: Leading/trailing hyphens removed
  6. Length Limit: Truncated to 100 characters if necessary

​
Slug Examples

TitleGenerated Slug
Hello Worldhello-world
Go's Context: A Deep Divegos-context-a-deep-dive
API/REST Patternsapirest-patterns
What??? No way!what-no-way
Multiple Spacesmultiple-spaces

​
Generated Template

The command creates a file with this structure:
content/your-slug.md
---
title: "Your Title Here"
date: "2026-03-03"
description: "Enter a short description here..."
tags: []
pinned: false
draft: false
---

## Introduction

Start writing here...

​
Frontmatter Fields

​
title
string
The post title from your command argument.
​
date
string
Auto-set to current date in YYYY-MM-DD format.
​
description
string
Short summary of the post content. Used for SEO meta description and social media previews.
​
tags
array
Empty array. Add tags like ["go", "web-development"] for categorization.
​
pinned
boolean
default:"false"
Set to true to pin this post to the top of your blog.
​
draft
boolean
default:"false"
Set to true to exclude from production builds. Use kosh build -drafts to include drafts.

​
Automatic Build

After creating the file, kosh new automatically runs a build: 
$ kosh new "Getting Started"
✅ Created: content/getting-started.md

🔄 Building site with new post...
📦 Building assets...
📝 Processing content...
This ensures your new post is immediately ready to preview with kosh serve.

​
Terminal Output

$ kosh new "My New Post"
✅ Created: content/my-new-post.md

🔄 Building site with new post...
📦 Building assets...
📝 Processing content...
   ✅ Content processed.
📄 Rendering pagination...
🏷️  Rendering tags...
🕸️  Rendering graph and metadata...
💾 Syncing to disk...
📊 Built 1 post in 0.8s (cache: 0/1 hits, 0.0%)

​
Error Handling

​
File Exists

If a file with the generated slug already exists, the command aborts: 
❌ Error: File already exists: content/my-post.md
Solution: Choose a different title or manually rename the existing file.

​
Empty Slug

If the title contains only special characters, the command aborts: 
❌ Error: Title produces empty slug after sanitization
Solution: Use a title with at least some alphanumeric characters.

​
Missing Title

If no title is provided: 
Usage: kosh new "My New Post Title"

​
Workflow Tips

​
Quick Draft Workflow

# Create draft
kosh new "Work in Progress"

# Edit frontmatter to mark as draft
vim content/work-in-progress.md
# Set: draft: true

# Preview drafts locally
kosh serve --dev -drafts

# Build without drafts for production
kosh build

​
Series/Category Workflow

# Create related posts with consistent naming
kosh new "Go Tutorial Part 1: Setup"
kosh new "Go Tutorial Part 2: Basics"
kosh new "Go Tutorial Part 3: Concurrency"

# Add consistent tags in each file
# tags: ["go", "tutorial", "series"]

​
File Permissions

Created files have permissions 0644 (rw-r—r—):
  • Owner: read and write
  • Group: read only
  • Others: read only
  • kosh build - Build the site (automatically run after new)
  • kosh serve - Preview your new post locally

Build docs developers (and LLMs) love

Get started for freeTalk to us