Skip to content
CAI
Software that uses CAICheck a score

rust-lang/mdBook

47.2

Weak · 14 November 2026

12.4k

lines of production code

Rust

with JavaScript

7

measurements over time

CAI band scale
CAI trend line
CAI lens gauges

What this system is

Features

Add bundled font assets and Ace editor library to mdbook HTML renderer

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 · high confidence

Add nop-preprocessor example demonstrating the preprocessor interface

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

Add remove-emphasis example with integration test

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

Add remove-emphasis preprocessor example

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

Added poll-based file watcher as an alternative to native OS notifications

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

Guide now displays the current project version

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

Introduce mdbook-core as the foundational library for book structure and configuration

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

Introduce mdbook-driver as the new high-level library entry point

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

Introduce mdbook-preprocessor library for implementing preprocessors

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

Introduce mdbook-renderer crate for implementing custom backends

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

New 'For Developers' guide section with backend and preprocessor documentation

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

New HTML renderer with robust heading ID generation

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

New documentation for the guide's file structure and Markdown features

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

New mdbook-compare utility for comparing mdbook outputs

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

New xtask CLI for development workflows

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

Architecture

Extracted summary parsing into a dedicated mdbook-summary crate

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

Behavioural changes

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

Built-in renderers moved to mdbook-driver crate

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

CLI commands restructured with new subcommand modules and argument helpers

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

Consolidated utility functions in mdbook-core

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

Introduce configurable markdown parsing options

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

Introduce new CLI entry point with structured subcommands and tracing-based logging

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

Migration to GitHub Actions with multi-platform build and release automation

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

New HTML rendering pipeline with admonition support

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

New HTML rendering pipeline with search and static asset management

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

New Handlebars helpers for TOC, resources, and icons in HTML renderer

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

Redesign of front-end assets and keyboard interaction logic

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

Redesigned HTML theme engine with new CSS architecture and syntax highlighting

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

Redesigned sidebar navigation with heading-level tracking and improved scroll behavior

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

Repository configuration and tooling setup

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

Theme assets are now embedded in the binary

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

Test coverage

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.

Dependencies

Bundled search libraries with license texts

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

mdBook 0.5.4 workspace restructure and dependency updates

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 cca.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.

How this codebase got here

Score

  • CAI 48 → 47 (-0.9)
  • Rubric changed (rubric-2026.10.5 → rubric-2026.11.4) — scores are not directly comparable.

Lenses

  • Code Health 52 → 67 (+15.4)
  • Architecture 96 → 96 (+0.0)
  • Maturity 53 → 53 (-0.2)
  • Readiness 64 → 63 (-0.1)
  • Security 43 → 38 (-5.3)
  • Accessibility 44 → 45 (+1.8)
  • Performance 100 → 100 (+0.0)

Resolved (32)

  • Flaky test: mdbook::testsuite.build::create_missing
  • Flaky test: mdbook::testsuite.build::dest_dir_relative_path
  • Flaky test: mdbook::testsuite.build::failure_on_missing_file
  • Flaky test: mdbook::testsuite.config::bad_config_top_level
  • Flaky test: mdbook::testsuite.config::config_json_from_env
  • Flaky test: mdbook::testsuite.config::env_invalid_config_key
  • Flaky test: mdbook::testsuite.includes::recursive_include
  • Flaky test: mdbook::testsuite.includes::unclosed_quote
  • Flaky test: mdbook::testsuite.init::basic_init
  • Flaky test: mdbook::testsuite.init::init_api
  • Flaky test: mdbook::testsuite.init::no_git_config_with_title
  • Flaky test: mdbook::testsuite.markdown::footnotes
  • Flaky test: mdbook::testsuite.markdown::tables
  • Flaky test: mdbook::testsuite.preprocessor::missing_optional_not_fatal
  • Flaky test: mdbook::testsuite.preprocessor::nop_preprocessor
  • Flaky test: mdbook::testsuite.print::relative_links
  • Flaky test: mdbook::testsuite.renderer::missing_optional_not_fatal
  • Flaky test: mdbook::testsuite.renderer::missing_renderer
  • Flaky test: mdbook::testsuite.rendering::default_rust_edition
  • Flaky test: mdbook::testsuite.rendering::fontawesome_error_message
  • …and 12 more

New (53)

  • Duplicated block (5 lines × 2) (crates/mdbook-html/src/html_handlebars/hbs_renderer.rs)
  • Edited copy of a member (17 corresponding lines) (crates/mdbook-driver/src/builtin_preprocessors/links.rs)
  • Edited copy of a member (17 corresponding lines) (crates/mdbook-driver/src/mdbook.rs)
  • Edited copy of a member (21 corresponding lines) (crates/mdbook-core/src/utils/html.rs)
  • FileTooLong: html_handlebars/hbs_renderer.rs (crates/mdbook-html/src/html_handlebars/hbs_renderer.rs)
  • Flaky test: mdbook::testsuite.build::no_reserved_filename (tests/testsuite/build.rs)
  • Flaky test: mdbook::testsuite.includes::multiline_include (tests/testsuite/includes.rs)
  • Flaky test: mdbook::testsuite.index::index_rewrite (tests/testsuite/index.rs)
  • Flaky test: mdbook::testsuite.index::readme_to_index (tests/testsuite/index.rs)
  • Flaky test: mdbook::testsuite.playground::disabled_playground (tests/testsuite/playground.rs)
  • Flaky test: mdbook::testsuite.print::chapter_no_h1 (tests/testsuite/print.rs)
  • Flaky test: mdbook::testsuite.print::noindex (tests/testsuite/print.rs)
  • Flaky test: mdbook::testsuite.redirects::redirects_are_emitted_correctly (tests/testsuite/redirects.rs)
  • Flaky test: mdbook::testsuite.renderer::backends_receive_render_context_via_stdin (tests/testsuite/renderer.rs)
  • Flaky test: mdbook::testsuite.renderer::failing_command (tests/testsuite/renderer.rs)
  • Flaky test: mdbook::testsuite.rendering::canonical_url_site_root (tests/testsuite/rendering.rs)
  • Flaky test: mdbook::testsuite.rendering::code_block_in_list (tests/testsuite/rendering.rs)
  • Flaky test: mdbook::testsuite.rendering::edit_url_template_explicit_src (tests/testsuite/rendering.rs)
  • Flaky test: mdbook::testsuite.rendering::first_chapter_is_copied_as_index_even_if_not_first_elem (tests/testsuite/rendering.rs)
  • Flaky test: mdbook::testsuite.rendering::heading_with_unbalanced_html (tests/testsuite/rendering.rs)
  • …and 33 more

Changes since last survey

  • 21 commits — 17 feature/other, 4 fixes

By area

  • (repo) — 11 commits
  • (root) — 3 commits
  • crates/mdbook-html — 2 commits
  • .cargo/audit.toml — 1 commit
  • crates/mdbook-core — 1 commit
  • crates/mdbook-driver — 1 commit
  • tests/gui — 1 commit
  • tests/testsuite — 1 commit

Notable commits

  • fix: Fix relative links to README.md files
  • fix: Merge pull request #3240 from NUAAwqy/taiyi/fix-test-help-description
  • fix: Merge pull request #3244 from Chocorean/fix-index-links
  • fix: fix: hide task list checkboxes from assistive technology
  • change: Merge pull request #3086 from SichangHe/chapter-mut-thin
  • change: Merge pull request #3229 from Chocorean/dev_ignore
  • change: Merge pull request #3241 from dalance/preload_js
  • change: Merge pull request #3250 from DanielEScherzer/pass-audit
  • change: Merge pull request #3251 from Chocorean/dev-bypass
  • change: Merge pull request #3252 from DanielEScherzer/update-pulldown-cmark
  • change: Merge pull request #3263 from GuillaumeGomez/update-pulldown-cmark
  • change: Merge pull request #3264 from Chocorean/dev_must_3225
  • change: Merge pull request #3265 from Chocorean/dev-3245
  • change: Update pulldown-cmark to 0.13.5
  • change: Update pulldown-cmark to 0.13.6
  • change: [cargo audit] Ignore pulldown-cmark RUSTSEC-2026-0414
  • change: [cargo audit] update tokio for RUSTSEC-2026-0386
  • change: add skip-to-content block for accessibility
  • change: feat(data_structure): ChapterMutThin for accessing in parallel
  • change: remove debug noise
  • …and 1 more

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

Survey your own repository

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.

About this page

  • The score is its most recent published measurement, taken on 14 November 2026 at a pinned commit. It is not a live figure and does not change until the project is measured again.
  • Measured at commit 1acf8fddf820d802270286f160f570a771c621c8 — the exact code this score is about.
  • Scored under rubric-2026.11.4 — the same rubric and the same method as every other entry in this index.
  • Measured by Canine Code Analyzer (cca.canine.dev) using cca measure-2026.11.65+preprod-36d4cd83012f.