Markdown plus SUMMARY.md produces a static book
mdBook starts with a strict and useful constraint: your publication is an ordered book. book.toml stores settings, src/SUMMARY.md lists the visible chapters, and the remaining Markdown files hold the text. Running mdbook build produces static HTML that can live on any Web server. There is no database, hosted account, or client framework to keep alive after deployment.
That structure is excellent for a manual that should read from chapter 1 onward. It is less comfortable for a sprawling product site. A chapter does not appear until it is added to SUMMARY.md, and the source folder layout becomes part of the output URL layout. Draft entries, nested chapters, part titles, prefix pages, and suffix pages give an author enough control without turning navigation into application code.
Rust examples receive first-class treatment
Rust code blocks can gain a play button, run in the Rust Playground, hide setup lines, or carry rustdoc-style attributes such as ignore, no_run, and compile_fail. The mdbook test command checks Rust examples. File includes can pull a whole source file, a line range, or a named anchor into a chapter, which reduces the chance that teaching code and compiled code drift apart.
The bias is deliberate. Authors documenting another language still get syntax highlighting and can define custom hidden-line prefixes, but the built-in example testing path is about Rust. Extensions can fill gaps through preprocessors and renderers. That power comes with process boundaries and configuration: mdBook sends structured data to external commands, and those commands have to stay installed and compatible in local and CI environments.
What happened when we ran it
Our sandbox installed 112 npm packages in 27 seconds, leaving 46 MB on disk. The checkout at commit ea1b91d contained 681 files, about 19,744 lines of source, and occupied 2.3 MB before that install. The environment was an unprivileged container with 3 CPUs and 8 GB of RAM. npm audit found 0 known vulnerabilities, including 0 at each reported severity.
There was no npm build script or target, so our harness skipped the build. There was also no npm test script or target, so it skipped tests. Those are findings, not passes. The repository's package.json contains lint scripts and two JavaScript development dependencies, while the product itself is written in Rust. Our 27-second npm result therefore says nothing about whether the Rust CLI compiled or its Rust test suite passed.
The repository does contain 4 CI workflow files and a tests directory. It does not contain a Dockerfile, which is unsurprising for a tool distributed as native executables and a Cargo package. Anyone evaluating source changes should run the Rust commands required by the contribution guide. Our supplied lab block did not do that, so this review makes no claim about their outcome.
Precompiled binaries avoid the Rust toolchain
The user guide offers ready-made executables for Windows, macOS, and Linux. Put the binary on PATH, run mdbook init, then use mdbook serve --open while writing. The server rebuilds after a saved edit and refreshes the browser. Publishing is equally plain: mdbook build writes the book directory, which can be copied to static hosting.
A source install needs Cargo and Rust 1.88 or newer. That is reasonable for Rust teams and unnecessary weight for a writing team, so the binary is the better default. The project does not need npm for ordinary book authoring. npm appears in contributor-facing browser and lint work, which explains why our harness found a valid package installation even though it could not build mdBook.
Version 0.5 requires a careful custom-theme migration
Release 0.5.4 arrived on July 6, 2026 with zoomable images, dependency updates, and several layout and packaging fixes. The larger 0.5 line changed much more. Its migration guide names breaking changes across custom themes, preprocessors, renderers, configuration keys, generated HTML, and the Rust API. Unknown configuration fields now error, and several older options were removed or renamed.
A plain Markdown book should be easier to move than a themed publication with third-party commands. Test the generated pages side by side before upgrading. Issue 3170 reports that an optional missing renderer can still fail a Linux build with a broken pipe under 0.5.4, while the same setup behaves correctly on macOS. That is exactly the sort of extension edge a simple sample book will not reveal.
The default HTML still has accessibility defects
Issue 3212 shows task-list checkboxes rendered without an accessible name in version 0.5.4. The report ties the output to WCAG 2.1 success criterion 4.1.2 and includes a small reproduction. Issue 3199 describes the / search shortcut failing on keyboard layouts that require Shift and colliding with Firefox Quick Find. A pull request opened on September 18 addresses that shortcut, which also shows the project responding to current reports.
Health is strong by ordinary repository signals. GitHub recorded a push on September 18, 2026, recent issue and pull-request movement, 22,158 stars, and 656 combined open issues and pull requests. The last number is a queue, not a bug total. mdBook remains a sound choice when its opinionated book structure matches the job. Its constraints become friction only when the publication wants to behave like a full website.