docs-gen

April 11, 2026 · View on GitHub

A zero-dependency static site generator for documentation. Just write Markdown and deploy — no plugins, no runtime, no extra tools required.

Documentation: https://yhirose.github.io/docs-gen/

The following sites are built with this tool:

Main Features

Built-in themes (dark/light)
Live-reload development server
Syntax highlighting
Client-side full-text search
Multi-language support with SEO (canonical URLs, hreflang, sitemap.xml)

Installation

cargo install docs-gen

Requires Rust. After installation, the docs-gen command is available globally.

Get Started

1. Create a project

docs-gen init my-docs

This generates config.toml and sample pages:

my-docs/
├── config.toml        # Site title, URL, footer, navigation
└── pages/
    ├── en/            # English pages
    │   ├── index.md       # Homepage
    │   ├── users-guide/       # Section (has its own sidebar)
    │   │   ├── index.md
    │   │   ├── *.md           # Pages with frontmatter
    │   │   └── screenshot.png # Images next to pages (colocation)
    │   └── developers-guide/  # Section for contributors
    │       ├── index.md
    │       └── *.md           # Pages with frontmatter
    └── ja/            # Japanese pages (same structure as en/)

2. Preview locally

docs-gen serve my-docs --open

The serve command watches your files and automatically reloads the browser whenever you save a change. Keep it running while you edit — every save is reflected instantly.

3. Edit config.toml

Update the settings for your site. The generated file includes comments explaining each field. See the User's Guide for more.

[system]
theme = "default"                          # Run `docs-gen theme list` to see options
langs = ["en", "ja"]                       # Language codes (first is default)

[site]
title = "My Docs"
version = "0.1.0"
hostname = "https://username.github.io"    # Your site's hostname
base_path = "/my-project"                  # URL path prefix (or "" if served from root)
footer_message = "© 2026 Your Name. All rights reserved."

[[nav]]
label = "Guide"
path = "users-guide/"

Add .md files anywhere under pages/en/ — they become pages automatically. Group related pages into subdirectories (each with an index.md) to create sections with sidebar navigation. Each page starts with a frontmatter header:

---
title: My New Page
order: 2            # Unique within the section, controls sidebar order
---

Your content here...

5. Check, build, and deploy

docs-gen check my-docs
docs-gen build my-docs docs

The docs/ directory is plain static HTML — deploy it to any hosting service.

GitHub Pages: commit and push docs/, then go to Settings > Pages, set Source to Deploy from a branch, and choose your branch with /docs folder. See the Deploying guide for GitHub Actions, Netlify, and other options.

For more details — image handling, multi-language setup, theme customization, and more — see the User's Guide.

Commands

Command	Description
`init [DIR] [--theme NAME]`	Scaffold a new project (default: current directory)
`serve [SRC] [--port PORT] [--open] [--theme NAME]`	Build and serve locally with live-reload
`build SRC OUT [--theme NAME]`	Generate static HTML for deployment
`check [SRC] [--fix]`	Check for broken links, duplicate orders, and other issues
`theme list`	List available built-in themes
`theme install NAME [SRC] [--force] [--with-base]`	Install theme style files for customization (add `--with-base` for templates and JS too)

Built-in Themes

Theme	Description
`default`	Dark/light theme with color accents
`monotone`	Calm, sophisticated grayscale-only theme (dark/light)

Use --theme NAME with init, serve, or build to select a theme. Each theme ships with a DESIGN.md describing its design intent and customization rules — useful when editing CSS yourself or with an AI coding agent. See the Customizing Themes guide for details.

For Theme Developers

Want to create your own theme? See the Creating a Theme guide. For more on docs-gen internals, see the Developer's Guide.

License

MIT