ADR-0010: mdBook and rustdoc for the Xianyun documentation

Status: accepted · Date: 2026-10-13 · Decision makers: James Hebden

Context and Problem Statement

The repository’s documentation site is a Hugo site that publishes the whole docs/ directory. That content describes the Go caproni binary, its commands are generated from the Go command tree, and its pages use caproni names and paths. Xianyun needed documentation that names the xianyun binary, treats the MCP server as the main way to use it, and includes API documentation for the Rust crates. A review on 2026-10-13 also found that publishing the new architecture, specification, and threat-model pages through Hugo would turn links into pages marked “never render” into links to a section index.

Decision Drivers

• The Rust API documentation should come from the Rust toolchain, not be written by hand
• The command reference shouldn’t drift from the binary
• The site should build in the same Nix development shell as the code
• The Go documentation should stay as it is until the Go binary is retired
• Light and dark themes and keyboard navigation without custom work

Considered Options

1. A separate mdBook for Xianyun, with rustdoc output merged under api/, and the Hugo site left for the Go docs
2. Rewrite the Hugo content for Xianyun
3. Hugo for prose and a separately hosted rustdoc site
4. Only rustdoc, with prose in crate-level documentation

Decision Outcome

Chosen option: “A separate mdBook with rustdoc merged under api/”, because mdBook is the standard prose companion to rustdoc, is packaged in nixpkgs, ships light and dark themes with search and keyboard navigation, and leaves the Go documentation untouched. Option 2 would mean rewriting pages for a binary the Hugo site’s other pages don’t describe, with the command reference generated from Go. Option 4 has no good home for task-oriented material such as connecting an agent.

The book lives in book/. The Xianyun-specific architecture decisions, specification, user stories, threat model, and the earlier Rust-rewrite notes moved into book/src/project/. The command reference is generated from xianyun --help by scripts/gen-cli-reference.sh, and scripts/build-docs.sh builds the book and the API reference together.

Consequences

Good:

• The API reference and the command reference are generated from the code
• Cross-references among ADRs, the specification, stories, and the threat model resolve inside one site
• A nix build .#docs output can be built in CI

Bad:

• Two documentation systems live in one repository until the Go tool is retired
• The threat model is published with the rest of the book, so its open findings are visible wherever the book is hosted. Leaving it out of SUMMARY.md would break the links from the ADRs and the specification.
• Some pages that lived under docs/ (the Rust rewrite notes and the VM test page) moved, so links from the Hugo documentation to them were replaced with plain paths
• Nothing deploys the book yet

Neutral:

• The repository’s Markdown linter now also covers book/src

Implementation Location

• book/book.toml
• book/src/SUMMARY.md
• scripts/build-docs.sh
• scripts/gen-cli-reference.sh
• nix/docs.nix

More Information

• Recorded on 2026-10-13, in the same change that created the book.
• Related: ADR-0001.
• Amended by ADR-0017: the Hugo site this ADR left in place for the Go documentation was removed along with that documentation, and the book is now published through GitLab Pages.