Documentation tooling and CI

Note

Project policy: accepted. The tools that build and check the documentation, how to run them locally, and what CI enforces.

The documentation is checked as strictly as code. Every tool used here is written in Rust (ADR-0002), and every check that runs in CI can be run locally with the same command.

Tools

Versions are pinned in .github/workflows/docs.yml. Upgrading a tool is a pull request that changes the pin and this table together.

Setting up locally

1. Install Rust with rustup. The repository’s rust-toolchain.toml selects the pinned toolchain automatically; see Toolchain and MSRV.

2. Install the prebuilt tools:

   $ cargo install cargo-binstall
   $ cargo binstall --locked mdbook@0.5.4 mdbook-mermaid@0.17.1 lychee@0.24.2 typos-cli@1.50.1 rumdl@0.2.73
   

Running the checks

Run these from the repository root. They are the same commands CI runs, in the same order.

$ cargo fmt --all --check
$ cargo clippy --workspace --all-targets -- -D warnings
$ cargo xtask docs-check
$ rumdl check .
$ typos
$ lychee --config lychee.toml './*.md' docs
$ mdbook build docs

The built site is written to target/book/. To preview it with live reload, run mdbook serve docs.

What cargo xtask docs-check enforces

The implementation lives in xtask/src/docs_check/, with one module per group of checks.

What the other tools enforce

• rumdl applies its default Markdown rules, with line length disabled because pages use one sentence per line.
• typos checks spelling across the repository, excluding build output and vendored files.
• lychee runs offline on pull requests and checks that every relative link and heading anchor resolves.
• mdBook fails the build if SUMMARY.md references a missing page or a preprocessor fails.

Vendored files

docs/mermaid.min.js and docs/mermaid-init.js are the browser-side Mermaid renderer used by the built site. They are generated by mdbook-mermaid install docs and are not edited by hand. When mdbook-mermaid is upgraded, rerun that command and commit the regenerated files. Linters exclude these files.

CI

The docs workflow in .github/workflows/docs.yml runs every check above on each pull request and on pushes to main.

• The workflow has read-only contents permission and does not persist checkout credentials.
• Third-party actions are pinned by commit SHA, with the release tag in a comment.
• A failing check blocks merging once branch protection is configured; see the maintainer handbook.

Planned additions

The weekly external-link workflow, 180-day specification-review warning, and main book-publication workflow are now configured for the first alpha. cargo xtask link-health checks public links; --report-issue explicitly enables the CI bot’s deduplicated issue report. Pull-request link checks remain offline.

Adding a check

1. Write the rule in the style guide and mark it (checked).
2. Implement it in a module under xtask/src/docs_check/, reporting problems with file and line.
3. Fix every existing page so the check passes.
4. Update the table in What cargo xtask docs-check enforces.