mdBook

mdBook is a command-line tool written in Rust that compiles a directory of Markdown chapters into a polished, searchable static website — the same tool that renders the official “The Rust Programming Language” book and much of the Rust project’s own documentation. It reads a SUMMARY.md table of contents and a book.toml configuration file, then runs each chapter through a Markdown-to-HTML pipeline with built-in search indexing, syntax-highlighted code blocks, and an in-browser theme switcher, distributed as a single self-contained binary with no Node.js or Ruby toolchain required.

Beyond the CLI itself, the project ships companion library crates — mdbook-driver, mdbook-preprocessor, and mdbook-renderer — that expose the same book-building pipeline programmatically, so other tools can transform content or plug in alternate output formats. A built-in mdbook serve live-reload server and mdbook watch file watcher make iterating on documentation fast, and the preprocessor/renderer plugin protocol (any external binary speaking its JSON stdin/stdout contract) has spawned a large ecosystem of community extensions for diagrams, admonitions, link-checking, and PDF export.

What You Get

• Static book generator - Compiles nested Markdown chapters defined in SUMMARY.md into a themed, navigable HTML site.
• Built-in search - Ships a client-side full-text search index (via the search feature) with no external service required.
• Live-reload dev server - mdbook serve rebuilds and refreshes the browser automatically as you edit chapters.
• Preprocessor & renderer plugin protocol - Any external binary that speaks mdBook’s JSON stdin/stdout contract can transform content or add output formats.
• Companion library crates - mdbook-driver, mdbook-preprocessor, and mdbook-renderer expose the same pipeline programmatically for embedding in other Rust tools.

Common Use Cases

• Rust project documentation - Powers the official ‘The Rust Programming Language’ book and dozens of other Rust ecosystem docs sites.
• Internal engineering handbooks - Teams write versioned, reviewable Markdown docs that build into a searchable internal site via CI.
• API and library guides - Maintainers pair mdBook with cargo doc output or custom preprocessors to publish narrative guides alongside generated reference docs.
• Offline/self-hosted documentation - Generates a fully static site that can be hosted anywhere or shipped as offline docs with no server-side dependency.

Under The Hood

Architecture The mdbook binary (src/main.rs, src/cmd/*) is a thin clap-based CLI shell over the workspace’s real engine: mdbook-driver’s MDBook struct (crates/mdbook-driver/src/mdbook.rs) owns the root path, parsed Config, in-memory Book, and ordered maps of Preprocessor and Renderer trait objects. Loading walks SUMMARY.md (crates/mdbook-summary) into a Book tree (crates/mdbook-driver/src/load.rs), preprocessors run in dependency order via a topological sort before rendering, and each configured renderer (built-in HTML via mdbook-html, built-in Markdown passthrough, or an external CmdRenderer/CmdPreprocessor subprocess speaking JSON over stdio) receives a RenderContext. This preprocessor-then-renderer pipeline, with the external-process escape hatch for both stages, is the abstraction the whole plugin ecosystem depends on — changing its JSON contract would break every third-party preprocessor and renderer in the wild.

Tech Stack A Cargo workspace of nine crates (core, driver, html, markdown, preprocessor, renderer, summary, compare, xtask) built on clap for CLI parsing, pulldown-cmark for Markdown parsing (pinned, called out in Cargo.toml as “part of the public API”), handlebars for HTML templating, and optional feature-gated stacks for watch (notify, notify-debouncer-mini, ignore) and serve (axum with the ws feature, tokio multi-thread runtime, tower-http). elasticlunr-rs powers the built-in search index. Rust edition 2024, MSRV pinned at 1.88.0 and synchronized across Cargo.toml, CI, and the install docs.

Code Quality Extensive test coverage: 18 files under crates/ and 19 under tests/testsuite/ contain #[test] functions, exercising build, config, init, CLI, search index, and Markdown-rendering behavior, plus a separate snapbox-driven CLI-output-diffing harness and a gui test binary. CI (.github/workflows/main.yml) runs the full workspace test suite across stable/beta/nightly/MSRV toolchains and six OS/target combinations, with a second --no-default-features pass to catch feature-flag regressions. Workspace-level clippy lints (correctness, complexity, exhaustive_enums/exhaustive_structs, missing_docs, unreachable_pub) are set to warn, and public APIs (mdbook-driver’s lib.rs, MDBook methods) carry doc comments at high density.

What Makes It Unique Rather than bundling every feature into one monolith, mdBook keeps its core small and pushes extensibility out to two escape hatches: an external-process preprocessor/renderer protocol (so third-party tools can be written in any language) and a set of standalone library crates (mdbook-preprocessor, mdbook-renderer) that let Rust programs embed the same pipeline mdBook itself uses, rather than shelling out. Combined with being the de facto tool for Rust’s own documentation ecosystem, this has produced an unusually large plugin ecosystem for what is otherwise a deliberately minimal static book generator.