docgen-rs

A Cargo-only static documentation-site generator. No npm, no Node.

Status

P0 (core SSG): markdown discovery, frontmatter, rendering, sidebar tree, static dist/ output via docgen build.

P1 (parity slice): server-side syntax highlighting of fenced code (comrak + syntect, zero runtime JS), [[wikilinks]]/[[target|label]] resolution with a backlinks section and broken-link marking, and a static search index (dist/search-index.json) served by a vendored, dependency-free Cmd/Ctrl-K search modal (dist/search.js + dist/docgen.css).

P2 (git diff timeline): every doc tracked in git gets a static /<slug>/history/index.html page showing its commit timeline with line-level and block-level diffs, plus a "History" link on the doc page. History is read with git2 (port of the original SvelteKit doc-diff timeline) and requires no runtime JS. Scope and limitations:

• Build-history mode only. Per-doc commit history is rendered; the dev-worktree mode (uncommitted/untracked changes) is deferred to P5.
• Graceful no-op. Building a project that is not inside a git repo, or a doc with no commit history, simply skips the history page (and omits its link) — the build never fails on this.
• Rename following emulates git log --follow via first-parent rename chains (no copy detection), matching the original's effective behavior.
• Depth. Each doc walks up to 50 commits by default; override with the DOC_DIFF_LIMIT env var (clamped to 1..=200).

See docs/superpowers/plans/ for the roadmap.

Install

Prebuilt binary (recommended — no toolchain)

With cargo-binstall:

cargo binstall docgen

Or download an archive for your platform from the Releases page and put docgen on your PATH.

From source

cargo install --path crates/docgen

Quick start

docgen init my-docs
cd my-docs
docgen dev          # http://localhost:4321 with live reload
docgen build        # static site in ./dist

docgen init scaffolds a buildable site: a docgen.toml, a docs/ tree with sample content exercising wikilinks, math and mermaid, a sample custom component under components/, and a .gitignore.

Usage

cargo run -p docgen -- build path/to/project

The project must contain a docs/ directory of .md files. Output is written to path/to/project/dist/.

Includes & partials

:include{src="./_part.md"} transcludes another markdown file (resolved relative to the including doc) and renders it through the full pipeline. Any .md file whose basename starts with _ is an include-only partial: it is excluded from page discovery (no standalone page, sidebar entry, or search result) but remains a valid :include target. Missing targets and include cycles degrade to an inert error span; the build never fails on a bad include.