Documentation development

The documentation is a tested product surface. Maintained Markdown spans the MkDocs site, repository entry points, first-party add-in READMEs, public evidence guidance, scripts, examples, tests, and GitHub contribution templates.

Reference

Surface: Local docs build, lint, spelling, navigation, links, and rendered-math behavior

Stability: Make targets are maintained contributor interfaces; visual theme internals may evolve

Use this page when: Editing documentation, reviewing a docs-only change, or reproducing the documentation CI gate

Authoritative commands

Data table with columns: Command, Purpose, Network requirement
Command	Purpose	Network requirement
`make docs-check`	Markdown lint, spelling, and strict MkDocs build	None after repository dependencies are installed
`make docs`	Strict static-site build	None after dependencies are installed
`make docs-serve`	Local server on `127.0.0.1:8000`	None for local navigation
`make docs-live-fast`	CLI surface smoke plus the documentation gate	None after dependencies are installed
`make docs-live`	Maintained full documentation alias	Same as `docs-live-fast`

Scroll horizontally to see every column.

docs-check validates every maintained repository Markdown file selected by the Makefile, not only docs/**/*.md. Generated, cached, vendored, dependency, and temporary-run trees are deliberately excluded.

Offline build versus browser rendering

MkDocs builds the site without fetching remote content. The generated pages reference MathJax from jsDelivr for browser-side equation rendering. Therefore:

prose, code, navigation, tables, images, and raw TeX remain available in a fully offline browser;
equations render typographically only when the browser can load that pinned MathJax URL or an operator supplies an approved local mirror; and
a successful offline build does not prove that a deployed browser may reach the CDN.

Do not weaken content-security policy or grant broad network access merely to render equations. Deployments requiring fully offline mathematical rendering should mirror the pinned asset and review the resulting site change.

Page-type contracts

Every MkDocs page under a typed section declares its reader contract near the top. Use a standard Markdown blockquote with a bold page-type label and bold field names. Separate each field with a quoted blank line so it stays a distinct paragraph in both GitHub and the published MkDocs site:

Data table with columns: Directory, Required opener
Directory	Required opener
`user-guide/`	Outcome, audience, prerequisites
`assurance/`	In plain language, question, decision use, evidence
`reference/`	Surface, stability, use-this-page-when
`security/`	In plain language, objective, assets or boundary, use-this-page-when

For example:

> **Assurance note**
>
> **In plain language:** Explain the supported result in ordinary terms.
>
> **Question:** State the question this page answers.
>
> **Decision use:** Explain how the reader can use the answer.
>
> **Evidence:** Identify the records or checks supporting the claim.

Use portable Markdown for content shared with GitHub. MkDocs-specific callout syntax exposes its indented fields as code on GitHub; escaping the asterisks also prevents bold labels. Keep literal Markdown examples inside fenced code blocks. Test both renderers when changing shared page structure.

The opener does not replace the page body. A user guide must complete and validate a task; reference must enumerate exact syntax and failure behavior; assurance must connect claims to observable evidence and limits; security must name adversaries, controls, residual risks, and response.

Describe the current repository state without calendar dates, dated status updates or development history. Use Git history and the changelog to trace changes. Keep public prose focused on the reader's task and supported behavior; internal experiment logs do not belong in an interface reference. Do not scatter publication-availability notices or hard-coded product pins across guides. Follow Matching wheels and examples: released wheels use their installed-version tag archive, and local wheels use their exact build checkout. Preserve contract versions, dependency constraints, historical evidence provenance, and v0.13 compatibility semantics.

Links and versioned contracts

Prefer relative links for pages and repository-owned assets in the same source tree.
Link public standards and upstream runtime documentation directly.
Treat links to mutable repository branches as source navigation, not a version guarantee. Installed contract copies and the selected release source remain authoritative.
Keep diagrams accessible with <title>, <desc>, and meaningful surrounding alt text.
When a command contains placeholders, label them and state what authority supplies the real value.

Review checklist

Before accepting a documentation change:

compare every command and option with current --help or the public API;
verify fields against package-owned schemas and implementation replay;
run at least one literal user journey affected by the change;
check failure and recovery behavior, not only the successful path;
confirm all new pages are present in navigation;
inspect desktop and narrow layouts when visual structure changes; and
run make docs-check from a clean source tree.

A green build proves syntax and internal site consistency. It does not by itself prove that claims match code; maintainers still need code-to-document traceability and a behavior check.