Building the docs locally

The docs site you’re reading is published from docs/book/. You can build the same site on your own machine, useful for offline reading, previewing edits before opening a PR, or developing translations.

One-command quickstart

sh

cargo mdbook serve                       # serve all locales at http://localhost:3000/en/
cargo mdbook serve --locale ja           # live-reload against Japanese source
cargo mdbook build                       # static build of every locale into docs/book/book/
cargo mdbook refs                        # regenerate the auto-generated reference pages
cargo mdbook sync                        # translation-cache pass: re-extract + merge .po files
cargo mdbook sync --locale ja            # sync one locale only
cargo mdbook sync --force                # force-retranslate everything (quality pass)
cargo mdbook sync --locale ja --force    # force-retranslate one locale
cargo mdbook stats                       # show translated/fuzzy/untranslated per locale
cargo mdbook check                       # validate .po format (run before a translation PR)

Always go through the cargo mdbook … wrapper. Running mdbook build directly from docs/book/ skips the xtask step that renders theme/lang-switcher.js from locales.toml, which fails the build with failed to open theme/lang-switcher.js for hashing.

Required tools

cargo mdbook will fail fast and tell you what’s missing, but for reference:

Tool	Install
`mdbook`	`cargo install mdbook --locked`
`mdbook-i18n-helpers`	`cargo install mdbook-i18n-helpers --locked`
`cargo`	https://rustup.rs
`gettext` (msgfmt, msgmerge)	`apt install gettext` / `brew install gettext`

What gets built where

Source	Output	Generated by
`docs/book/src/*/.md` (hand-written)	`docs/book/book/<locale>/`	`mdbook build`
`docs/book/src/reference/cli.md`	(same path; gitignored)	`cargo run -- markdown-help`
`docs/book/src/reference/config.md`	(same path; gitignored)	`cargo run -- markdown-schema`
`target/doc/` (rustdoc)	`docs/book/book/api/`	`cargo doc --no-deps --workspace`

The two reference/*.md files are generated from the actual clap derives and JSON schema in the code, never edit them by hand. Edit the /// doc comments on the relevant Rust types instead.

cargo mdbook is an alias for cargo run -p xtask --bin mdbook -- (defined in the cargo config).

Translations

English markdown is the only source maintained by humans. Translations live in docs/book/po/<locale>.po files that act as a cache, and cargo mdbook sync keeps them current. Routine English docs PRs do not need to carry the generated .po churn: leave it for a dedicated translation-cache PR. For the full translation pipeline (app strings, docs, zerocode, adding a locale, release passes), see Docs & Translations.

Tips

Fast iteration on prose: cargo mdbook serve auto-rebuilds on save. Skip cargo mdbook refs unless you’ve changed CLI flags or config schema.
Fast iteration on translations: edit po/<locale>.po and reload the browser, mdbook serve detects .po changes and rebuilds automatically.
Cleaning up: rm -rf docs/book/book target/doc removes everything generated.
Zero-cost re-runs: cargo mdbook sync against unchanged English source completes in seconds, no AI calls, no cost.

Keyboard shortcuts