rust-lang/mdBook

This system is mdBook, a command-line tool and Rust library for creating static documentation websites from Markdown source files. It orchestrates a build pipeline that parses book structures, applies configurable preprocessors, and renders content into self-contained HTML output with features like client-side search, syntax highlighting, and interactive code playgrounds. The system supports extensibility through custom preprocessors and renderers, and includes utilities for development workflows, testing, and comparing documentation outputs.

12 changes.

The project underwent a significant architectural shift by reorganizing into a Cargo workspace with dedicated crates for core, driver, and renderers, while simultaneously modernizing the CLI with structured subcommands and tracing-based logging. This period also focused on enhancing developer experience through comprehensive documentation, preprocessor examples, and robust CI/CD automation via GitHub Actions. Additionally, the codebase improved its reliability and test coverage by introducing poll-based file watching and a new GUI test suite.

26 changes.

The project restructured into a multi-crate monorepo, introducing dedicated libraries for core logic, summaries, preprocessors, and renderers. Simultaneously, the HTML renderer was completely rewritten with a new pipeline, embedded assets, and enhanced features like search and admonitions. Development workflows were also modernized with a new xtask CLI and comprehensive integration tests.

The mdbook HTML renderer now includes its own front-end assets, specifically the Open Sans and Source Code Pro fonts (with their respective Apache and SIL Open Font licenses) and the Ace code editor library. This change moves these resources into the \crates/mdbook-html/front-end\ directory, ensuring that generated HTML books have the necessary styling and interactive code-playground capabilities bundled locally rather than relying on external CDNs.

_crates/mdbook-html/front-end/fonts, crates/mdbook-html/front-end/playground\editor · high confidence

The examples directory now includes a nop-preprocessor.rs file that serves as a reference implementation for developers building custom mdbook preprocessors. This example demonstrates how to structure a preprocessor application using clap for command-line argument parsing, specifically showing how to implement the Preprocessor trait, handle the 'supports' subcommand to declare renderer compatibility, and process book data via stdin/stdout. It also includes unit tests illustrating the expected input JSON structure and how to validate that a preprocessor correctly processes book content without modification.

examples · high confidence

A new example project demonstrates the remove-emphasis preprocessor, providing a complete MDBook setup (book.toml, source files) that invokes the mdbook-remove-emphasis command. An integration test verifies that the preprocessor correctly strips italic and bold emphasis markers from the generated HTML output.

examples/remove-emphasis · high confidence

The examples/remove-emphasis/mdbook-remove-emphasis directory now contains a working mdBook preprocessor that strips emphasis (italics and bold) from markdown content. Users can use this as a reference implementation for building custom preprocessors that modify book content by filtering out specific Markdown tags during the build process.

examples/remove-emphasis/mdbook-remove-emphasis · high confidence

The watch command now includes a new poll-based file watcher implementation (src/cmd/watch/poller.rs) alongside the existing native OS notification watcher (src/cmd/watch/native.rs). This provides a fallback mechanism for environments where native change notifications are unreliable or unavailable, ensuring that source file changes are still detected and the book is rebuilt correctly. Both implementations share the same core logic for loading the book, applying configuration updates, and filtering files based on .gitignore rules.

src/cmd/watch · high confidence

A new mdBook preprocessor in the guide-helper crate automatically injects the project's version number into the guide's first page. It replaces specific markers ({{ mdbook-version }}, {{ mdbook-semver }}, {{ mdbook-semver-break }}) with the version parsed from the root Cargo.toml, ensuring the documentation always reflects the correct release version.

guide/guide-helper · high confidence

The \mdbook-core\ crate has been added to provide the core data structures and configuration handling for mdbook. This includes the \Book\ and \Chapter\ types that represent the book's tree structure, along with iteration and mutation utilities, and the \Config\ struct which manages \book.toml\ settings, environment variable overrides, and strict validation of unknown fields. This change establishes the internal library layer that other mdbook components depend on for book representation and configuration management.

crates/mdbook-core/src · high confidence

The mdbook-driver crate is now available as the primary interface for programmatically managing and building mdBook projects. It exposes the MDBook struct for loading existing books and the BookBuilder helper for initializing new ones, including support for creating directory structures, stub content, and optional theme copying. The library also provides built-in support for running preprocessors and renderers, with configuration loaded from book.toml and environment variables, and includes a new search feature enabled via the 'search' cargo feature.

crates/mdbook-driver/src · high confidence

A new \mdbook-preprocessor\ crate has been added to provide the core types and traits needed to implement mdBook preprocessors. This library exposes the \Preprocessor\ trait, which allows developers to define custom logic that runs on a book before rendering, including methods for the preprocessor's name, the main \run\ method, and a \supports\_renderer\ hint. It also provides the \PreprocessorContext\ struct, which gives preprocessors access to the book's root path, configuration, renderer name, and mdBook version, along with a \parse\_input\ helper to deserialize the input stream into the context and book structure.

crates/mdbook-preprocessor/src · high confidence

The new \mdbook-renderer\ crate provides the core library and types needed to implement custom mdBook renderers. It exposes the \Renderer\ trait, which allows developers to define custom backends, and the \RenderContext\ struct, which supplies the book data, configuration, and output directory to the renderer. This crate serves as the primary interface for third-party tools to integrate with mdBook's rendering pipeline.

crates/mdbook-renderer · high confidence

A new 'For Developers' section has been added to the guide, providing detailed documentation on extending mdBook. This includes a README overview of the build process and library usage, a comprehensive guide on creating alternative backends (with a Rust word-count example), and instructions for implementing preprocessors in both Rust and Python. The documentation also links to specific API references for \mdbook-driver\, \mdbook-renderer\, and \mdbook-preprocessor\.

_guide/src/for\developers · high confidence

The \mdbook-html\ crate introduces a new HTML rendering pipeline, including utilities for generating unique, normalized heading IDs. This implementation ensures that headings consisting entirely of punctuation or whitespace fall back to a 'section' ID, and automatically appends numeric suffixes to resolve collisions, improving the reliability of internal links in generated documentation.

crates/mdbook-html/src · high confidence

The guide now includes a dedicated 'Format' section that explains how to structure a book, configure the SUMMARY.md file, and utilize mdBook-specific Markdown extensions. This new content covers hiding code lines, using the Rust playground, including file portions via anchors, and enabling features like MathJax, strikethrough, footnotes, and tables.

guide/src/format · high confidence

A new \mdbook-compare\ utility has been added to help users compare the HTML output generated by two different versions of mdbook. The tool accepts two mdbook executables and book directories as arguments, builds the books using each version, normalizes the resulting HTML using the \tidy\ command-line tool, and then uses \git diff\ to display the differences between the two outputs.

crates/mdbook-compare · high confidence

A new \xtask\ CLI utility has been added to streamline local development tasks. It provides commands to run the full test suite, linting (Clippy, ESLint), documentation generation, and formatting checks. Additionally, it includes a \bump\ command to update version numbers across the workspace and a \changelog\ command to automatically generate release notes by fetching pull request details from the repository.

crates/xtask · high confidence

The logic for parsing the \SUMMARY.md\ file structure has been moved from the core crate into a new, standalone \mdbook-summary\ crate. This change introduces public types such as \Summary\, \Link\, and \SummaryItem\ with \\#\[non\_exhaustive\]\ attributes to allow for future extensibility without breaking changes. The parser now utilizes the \tracing\ library for logging instead of \log\, and exposes the \SectionNumber\ type from \mdbook-core\ to support section numbering in the parsed summary items.

crates/mdbook-summary/src · high confidence

The built-in preprocessors (CmdPreprocessor, IndexPreprocessor, and LinkPreprocessor) have been relocated from the mdbook crate into the mdbook-driver crate, making them available as part of the driver's public API. This move includes a fix to the LinkPreprocessor to correctly support file paths containing spaces when using double quotes in include directives, and ensures that the CmdPreprocessor resolves command paths relative to the book root.

_crates/mdbook-driver/src/builtin\preprocessors · high confidence

The built-in renderers, including the Markdown renderer and the command-based CmdRenderer, have been relocated from their previous location into the mdbook-driver crate. This change consolidates renderer logic within the driver module, making these components part of the core rendering pipeline rather than a separate library. Users relying on internal paths to these renderers will need to update their imports to reflect the new module structure.

_crates/mdbook-driver/src/builtin\renderers · high confidence

The command-line interface in src/cmd has been reorganized into dedicated subcommand modules (build, clean, init, serve, test, watch) that share a common argument-prelude helper (command\_prelude.rs). This change introduces shared argument helpers like arg\_dest\_dir, arg\_root\_dir, and arg\_open, and updates the init command to support new flags such as --theme, --force, --title, and --ignore. The serve command now supports socket activation via --socket-activate and uses axum for HTTP serving with live reload over WebSocket. The clean command now displays detailed removal statistics (files, directories, bytes). The test command gains a --chapter option to test specific chapters. The watch command supports both poll and native file watching modes. These changes improve CLI usability, add new configuration options, and enhance the serve/watch experience with better file watching and live reload capabilities.

src/cmd · high confidence

The filesystem, HTML escaping, and TOML helper utilities have been consolidated into the \mdbook-core\ crate. This change centralizes common functionality such as file I/O with improved error handling, HTML character escaping, and TOML dotted-key access, making these tools available as shared internal resources for other mdbook components.

crates/mdbook-core/src/utils · high confidence

The mdbook-markdown crate now exposes a MarkdownOptions struct that allows users to control specific parsing features. By default, smart punctuation (converting quotes and dashes), definition lists, and admonitions are enabled. Users can disable these features by setting the corresponding boolean flags in the options struct when creating a new markdown parser.

crates/mdbook-markdown/src · high confidence

The application now uses a dedicated \src/main.rs\ entry point that replaces the previous \src/lib.rs\ test stub. This change introduces a structured CLI interface using \clap\, supporting subcommands for \init\, \build\, \clean\, \test\, and \completions\, with optional \watch\ and \serve\ commands gated by features. Logging has been migrated to the \tracing\ ecosystem, configured via the \MDBOOK\_LOG\ environment variable, and includes logic to silence noisy dependencies like \handlebars\ and \html5ever\ by default. The entry point also handles book directory resolution and integrates the \opener\ crate for opening the generated book in a web browser.

src · high confidence

The continuous integration system has been switched from the previous provider to GitHub Actions. This change introduces new scripts to handle Rust toolchain installation with support for cross-compilation targets (including x86\_64 and aarch64 Linux musl builds), automated creation of release assets for Ubuntu, macOS, and Windows, and publishing of crates to crates.io. Additionally, the user guide is now automatically published to GitHub Pages, with pre-release versions deployed to a separate directory to avoid overwriting stable documentation.

ci · high confidence

The HTML generation in mdbook has been replaced with a new rendering pipeline that processes markdown into a tree structure before serialization. This change introduces native support for admonitions (Note, Tip, Important, Warning, Caution), which are now rendered with specific icons and semantic tags. The new system also improves code block handling by supporting line hiding via prefixes or Rust-specific \\#\ markers, and fixes issues with print page link resolution and ID collisions across chapters.

crates/mdbook-html/src/html · high confidence

The Handlebars-based HTML renderer has been moved into the mdbook-html crate, introducing a new rendering pipeline that manages static files (CSS, JS, fonts) and generates a client-side search index using elasticlunr. This change includes cross-platform path normalization for resource lookups, support for canonical site URLs, and the integration of search functionality into the generated HTML output.

_crates/mdbook-html/src/html\handlebars · high confidence

The HTML rendering pipeline now includes dedicated Handlebars helpers for generating the table of contents, resolving resource paths, and rendering Font Awesome icons. The TOC helper constructs the navigation list, supporting chapter folding and section labels, while the resource helper resolves hashed asset paths. Icon rendering has switched to embedded SVGs via a new helper that validates Font Awesome types and names, providing clearer error messages for invalid inputs.

_crates/mdbook-html/src/html\handlebars/helpers · high confidence

The front-end JavaScript and assets have been updated to improve accessibility and visual consistency. Icons now use embedded SVGs instead of fonts, and the favicon has been updated to support dark mode. Keyboard navigation has been refined: global keypress handlers now correctly ignore shadow DOM elements and the ACE editor, and the zoom feature now supports keyboard shortcuts including Escape to zoom out. Additionally, all HTML IDs have been prefixed to prevent collisions, and license texts for bundled libraries (clipboard.js, highlight.js) and artwork have been added.

crates/mdbook-html/front-end/js · high confidence

The HTML output theme has been completely overhauled, introducing a new CSS structure that separates global variables, UI chrome, and content styles. This update brings a refreshed visual design with improved typography, layout, and spacing, including support for RTL books and better mobile responsiveness. Syntax highlighting for code blocks is now provided by dedicated theme files (e.g., Ayu, Tomorrow Night, Base16) with enhanced contrast and color schemes. The UI chrome has been modernized with embedded SVG icons replacing font-based icons, a sticky menu bar, and a new sidebar navigation system. Additionally, new content features such as admonitions (callouts), definition lists, and image zooming are now supported with corresponding styles.

crates/mdbook-html/front-end/css · high confidence

The HTML front-end templates have been restructured to support a new sidebar navigation system. The \index.hbs\ template now includes a dedicated sidebar container (\mdbook-sidebar\) and a sticky menu bar with theme and search toggles, while \head.hbs\ and \header.hbs\ provide customizable hooks for site-wide head content and page headers. The \toc.js.hbs\ script has been significantly enhanced to dynamically populate the sidebar, track the current page, and manage sidebar scroll positions to maintain context when navigating. Crucially, it now supports dynamic heading navigation within chapters (controlled by \sidebar\_header\_nav\), allowing users to jump to specific sections within a page, with logic to handle scroll thresholds and active state highlighting. The \redirect.hbs\ template now supports fragment-based redirects, and \toc.html.hbs\ provides a fallback iframe-based table of contents for non-JavaScript environments.

crates/mdbook-html/front-end/templates · high confidence

This change establishes the foundational configuration for the mdBook repository, introducing several new files to standardize development workflows and repository hygiene. It adds a \.gitattributes\ file to enforce consistent line endings (LF) and explicitly mark font and image files as binary, ensuring cross-platform consistency. A \.git-blame-ignore-revs\ file is created to exclude bulk formatting commits (specifically those related to \rustfmt\ and the 2024 style edition) from \git blame\ output, making code history easier to read. The repository also adopts \rustfmt.toml\ to set the style edition to 2024, \eslint.config.mjs\ to lint JavaScript and Handlebars templates with specific rules, and \typos.toml\ to configure spell-checking exclusions for generated or minified files. Additionally, \triagebot.toml\ is added to automate issue and pull request labeling (e.g., \S-waiting-on-review\), and \.gitignore\ is expanded to ignore IDE settings, build artifacts, and GUI test dependencies.

(repo-wide) · high confidence

The HTML renderer now bundles all default theme resources—CSS, JavaScript, fonts, templates, and images—directly into the binary using Rust's \include\_bytes!\ macro. This change removes the runtime dependency on external theme files for the default look and feel, ensuring that the generated documentation is self-contained and portable without requiring a separate theme directory to be present on the target system.

crates/mdbook-html/src/theme · high confidence

Added comprehensive GUI test suite for mdBook; Added test coverage for BookTest pass/fail scenarios; Added test suite for file includes and multiline code blocks; Added tests for preprocessor and renderer configuration defaults and ordering; New BookTest-based integration testsuite.

The front-end search functionality now includes the elasticlunr (v0.9.5) and mark.js (v8.11.1) libraries as bundled assets, accompanied by their respective MIT license texts. This ensures that the search and text-highlighting features are self-contained within the distribution while maintaining compliance with the open-source licenses of these third-party dependencies.

crates/mdbook-html/front-end/searcher · high confidence

This release updates mdBook to version 0.5.4 and restructures the project into a Cargo workspace. The codebase is now split into dedicated crates: mdbook-core (base support), mdbook-driver (high-level orchestration), mdbook-html (HTML renderer), mdbook-markdown (markdown processing), mdbook-preprocessor, mdbook-renderer, and mdbook-summary. Key dependency updates include pulldown-cmark to 0.13.4, handlebars to 6.4.3, and the HTTP server stack to axum 0.8.9 (replacing warp). The project also raises the Minimum Supported Rust Version (MSRV) to 1.88.0 and adopts the Rust 2024 edition. Front-end tooling updates include browser-ui-test to 0.25.1 and eslint to 10.0.0.

(dependencies) · high confidence

Written by watchdog.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.

• CAI 36 → 58 (+21.7)
• Rubric changed (rubric-2026.08.15 → rubric-2026.09.15) — scores are not directly comparable.

• Code Health 36 → 84 (+47.9)
• Architecture 96 (new)
• Maturity 59 → 53 (-5.6)
• Readiness 25 → 65 (+40.3)
• Security 60 → 77 (+16.7)
• Accessibility 50 (new)

• Change coupling: book.js ↔ searcher.js (crates/mdbook-html/front-end/js/book.js)
• Dimension evaluation failed
• Hotspot: crates/mdbook-html/front-end/js/book.js (crates/mdbook-html/front-end/js/book.js)
• Hotspot: crates/mdbook-html/front-end/searcher/searcher.js (crates/mdbook-html/front-end/searcher/searcher.js)
• LLM evaluation failed
• Medium: security finding (details withheld)
• Medium: security finding (details withheld)
• Medium: security finding (details withheld)
• Medium: security finding (details withheld)
• Medium: security finding (details withheld)
• Medium: security finding (details withheld)
• Medium: security finding (details withheld)
• Medium: security finding (details withheld)
• Medium: security finding (details withheld)
• Medium: security finding (details withheld)
• Medium: security finding (details withheld)
• Medium: security finding (details withheld)
• Medium: security finding (details withheld)
• Medium: security finding (details withheld)
• Medium: security finding (details withheld)
• …and 29 more

• CI installs an unverified third-party binary (.github/workflows/main.yml)
• Change coupling: mod.rs ↔ take_lines.rs (crates/mdbook-core/src/utils/mod.rs)
• ClassTooLong: MarkdownTreeBuilder (crates/mdbook-html/src/html/tree.rs)
• Clean::new (cognitive 20) (src/cmd/clean.rs)
• Dependency advisory scan runs only on code events
• Dependency hygiene PARTLY measured — Cargo dependencies read, dependency currency not (crates.io unreachable)
• Duplicated block (12 lines × 2) (crates/mdbook-core/src/utils/html.rs)
• Duplicated block (5 lines × 2) (crates/mdbook-html/src/html_handlebars/hbs_renderer.rs)
• Duplicated block (5 lines × 2) (crates/mdbook-html/src/html_handlebars/static_files.rs)
• Duplicated block (6 lines × 2) (crates/mdbook-html/src/html/tree.rs)
• Duplicated block (7 lines × 2) (crates/mdbook-core/src/utils/html.rs)
• FileTooLong: html/tree.rs (crates/mdbook-html/src/html/tree.rs)
• FileTooLong: js/book.js (crates/mdbook-html/front-end/js/book.js)
• FixmeComment (crates/mdbook-driver/src/mdbook.rs)
• FixmeComment (crates/mdbook-html/src/html_handlebars/hbs_renderer.rs)
• FixmeComment (src/cmd/build.rs)
• FixmeComment (src/cmd/watch/poller.rs)
• Flaky test: mdbook::testsuite.build::basic_build
• Flaky test: mdbook::testsuite.build::book_toml_isnt_required
• Flaky test: mdbook::testsuite.build::dest_dir_relative_path
• …and 138 more

• 78 commits — 60 feature/other, 18 fixes

• (repo) — 34 commits
• tests/testsuite — 11 commits
• (root) — 9 commits
• crates/mdbook-driver — 7 commits
• .github/workflows — 5 commits
• crates/mdbook-html — 4 commits
• tests/gui — 3 commits
• guide/src — 2 commits
• crates/mdbook-core — 1 commit
• examples/remove-emphasis — 1 commit
• src/cmd — 1 commit

• fix: Fix #2395
• fix: Fix new cargo/clippy lints
• fix: Fix playground selector
• fix: Merge pull request #3092 from ChrisJr404/fix/punctuation-heading-id-3002
• fix: Merge pull request #3163 from alexchen-sys/fix/include-path-spaces-2812
• fix: Merge pull request #3189 from VXNCXNX/fix/toc-index-chapter-highlight
• fix: Merge pull request #3190 from VXNCXNX/fix/rtl-fold-chevron
• fix: Merge pull request #3191 from VXNCXNX/fix/infostring-paren-comment-3188
• fix: Merge pull request #3218 from dalance/fix/playground-selector
• fix: Merge pull request #3222 from mmustafasenoglu/fix/cross-platform-path-separator
• fix: fix(links): address review feedback — DRY, escape semantics, trim removal
• fix: fix(links): emit explicit error on unclosed quoted path
• fix: fix(links): support double quotes for paths with spaces
• fix: fix(links): support spaces in #include file paths
• fix: fix: definition list in Chrome
• fix: fix: don't highlight the first chapter when another one is the index
• fix: fix: normalize path separators for cross-platform resource lookup
• fix: fix: point the fold chevron down in RTL books
• change: Add LLM policy
• change: Add cargo audit to the Github CI
• …and 58 more

Written by watchdog.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.

rust-lang/mdBook was measured the same way every project in this corpus was: the same rubric, at a pinned commit, with the result published in full. Point a surveyor at a repository you know and see whether you agree with it.