Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Documentation website

The mzstd book is built with mdBook and published through GitHub Pages. All pages in docs/ and architecture/ are included, along with their charts, CSV measurements, and environment records. Edit those files directly: there is no second maintained copy of the documentation.

Build locally

Requires Python 3.10+ and the pinned book tools:

cargo install mdbook --version 0.5.4 --locked
cargo install mdbook-mermaid --version 0.17.1 --locked
python3 scripts/docs.py build

Open target/book/index.html, or serve the book with:

python3 scripts/docs.py serve

The server listens on http://127.0.0.1:3000. Stop and rerun it after editing source Markdown: the server watches the generated source tree rather than the canonical directories. No Node.js installation or runtime CDN is needed. Mermaid assets come from the pinned preprocessor and are served with the book.

How source files become pages

scripts/docs.py copies docs/ and architecture/ into ignored target/book-src/, creates a table of contents, extracts Mermaid’s bundled JavaScript into target/book-assets/, then invokes mdbook build using the root book.toml. The output goes to target/book/. In the staged copy, README pages are renamed to index.md and the introductory page becomes the root index.md; their links are rewritten to match.

The sidebar has five parts in reading order: Start here, Guides, Performance and correctness, How it works, and Contributing. GUIDE_PARTS and CONTRIBUTING in scripts/docs.py hold the curated order. Nested chapters, such as the per-level benchmark pages, stay folded until their parent is opened.

Architecture entries follow the tables in architecture/README.md. Each ## section there that holds a specification table becomes a generated landing page under architecture/sections/, with its specifications nested beneath it. Every source Markdown file must appear in the table of contents: a missing architecture entry fails preparation. A new guide page is included automatically at the end of Guides until it receives a curated position.

Relative links between published pages stay local. Links to source files outside the published directories point to GitHub’s main branch. Code fences are preserved. The staged index pages become index.html pages. The build checks local files and heading anchors after rendering, including HTML links, images, and downloaded benchmark data. It also resolves every link from the root README.md into the published site, so renaming a guide without updating the README fails the build.

Theme and diagrams

book-theme/custom.css sets the palette for the default light theme and the navy dark theme, and styles tables, the sidebar, and the landing page (docs/introduction.md). book-theme/diagram-zoom.js opens a Mermaid diagram at its natural size when it is clicked or activated from the keyboard; Close or Esc returns it to the page. Both files are plain CSS and JavaScript with no build step.

Check the examples

python3 scripts/docs.py test-examples

This compiles and runs each Rust program in the guides listed in RECIPES in scripts/docs.py against the local crate with std and framed features, plus Rayon. A fenced rust block in those guides must be a complete program. Each program checks its decoded result. Temporary consumer source and build products remain under target/book-examples/.

Publish with GitHub Pages

In the repository settings, select Pages → Build and deployment → Source → GitHub Actions once. .github/workflows/pages.yml then:

  1. Builds and validates the book on pull requests and pushes to main.
  2. Compiles and runs the documented recipes.
  3. Uploads the static book as a Pages artifact.
  4. Deploys only on main pushes or a manual run on main.

Pull requests validate without publishing or receiving Pages write permissions. Deployment uses the github-pages environment and GitHub’s Pages actions; there is no generated-content branch. The site lives under /mzstd/, and relative asset links support that prefix and local previews.

See documentation architecture for the source/build boundaries and the CI specification.