Skip to content
Blume
Esc
↑↓navigate↵open⌘Jpreview

Blume vs mdBook.Your mdBook, as a full docs site.

mdBook turns Markdown into a clean, navigable book from one Rust binary. Blume turns the same Markdown into a docs site with llms.txt, an MCP server, API references, versioning, and translations built in, and an agent does the move.

npx blume migrate mdbook --codex
Blume and mdBook at a glance
BlumemdBook
You maintainBlumeA folder of Markdown, plus one optional config filemdBookbook.toml, a hand-written SUMMARY.md, and each plugin's executable
RuntimeBlumeNode.js 22.19 or latermdBookOne Rust binary, prebuilt for Windows, macOS, and Linux
LicenseBlumeFree and open source (MIT)mdBookFree and open source (MPL-2.0)
SearchBlumeLocal search with no keys, or Pagefind, Algolia, and more by adaptermdBookBuilt-in text search that runs in the browser
Code examplesBlumeHighlighted code blocks, not compiled or runmdBookmdbook test compiles Rust samples, and a play button runs them
Agent featuresBlumellms.txt, Markdown mirrors, and a JSON API by default; an opt-in MCP servermdBookNot built in
VersioningBlumeblume version snapshots with a switcher and scoped searchmdBookNot built in
LanguagesBlumeblume translate fills in every locale with your coding agentmdBookOne language per book; translations through the mdbook-i18n-helpers plugin

mdBook details are from its own pages as of October 7, 2026: Installation, mdbook test, Search and output, Plugins, Versioning issue, i18n helpers. Something out of date? Let us know

Your docs come with you.Your chapters keep their paths, and an agent does the move.

SUMMARY.md becomes folders.
Parts become sidebar headings, parent chapters become collapsible groups, and every chapter keeps its path.
Old .html links redirect.
The agent adds a redirect from every old .html URL, carries over [output.html.redirect], and pins any heading anchor that changed.
Included code stays generated.
{{#include}} anchors and line ranges become excerpts that a bundled script writes from your source before every build.
Code blocks and admonitions convert.
Hidden Rust lines and fence attributes like rust,ignore are stripped, and mdbook-admonish blocks become ::: callouts.

mdBook

Blume

  • book.tomlblume.config.ts
  • SUMMARY.mdmeta.ts
  • guide/README.mdguide/index.md
  • /guide/setup.html/guide/setup
  • {{#include f.rs:main}}<include>
  • ```rust,ignore```rust
  • ```admonish tip:::tip

When mdBook might suit you better.Blume isn't the right fit for every team.

You test your examples with mdBook.
mdbook test compiles the Rust samples in your book, and a play button runs them and shows the output. Blume renders code blocks without compiling or running them.
You want one binary and no Node.js.
mdBook installs as a single prebuilt binary for Windows, macOS, and Linux, so a Rust project's docs need no JavaScript toolchain. Blume needs Node.js 22.19 or later to build.
You're writing a book.
mdBook numbers chapters in the sidebar, prints the whole book as one page, and renders other formats through backends. Blume is a docs site, and exports one page at a time.
Migrate from
  1. 1

    Run one command in your docs project.

    Using Claude Code? Swap --codex for --claude.

  2. 2

    Review the agent's edits.

    It follows Blume's migration playbook for , rewriting your config and pages in place, so you review the whole move as one diff.

  3. 3

    Preview the result.

    Run npx blume dev, then read the agent's summary of anything it dropped or approximated.

Questions, answered.About moving from mdBook to Blume.

Why move from mdBook?

mdBook makes a clean book from one binary, but llms.txt, versioning, translations, and API references aren't built in. Blume ships all four, plus Markdown mirrors and an MCP server, from the same folder of Markdown.

Can I keep my chapters and URLs?

Yes. npx blume migrate mdbook --codex rebuilds SUMMARY.md as folders that keep each chapter's path, adds a redirect from every old .html URL, and pins any heading anchor that changed.

What happens to my includes and tested examples?

Code includes become excerpts that a bundled script generates from your source before every build, so the code cargo compiles is still the code readers see. Blume doesn't run mdbook test or the play button, so examples written only in a page aren't compiled any more.

Do I need Node.js?

To build, yes: Blume needs Node.js 22.19 or later, and a static build needs nothing at runtime. The agent puts package.json beside book.toml, so it stays out of your Rust repo's root.

What doesn't the migration carry over?

Running and testing code (the play button, editable examples, and mdbook test), the hidden-line toggle, the whole-book print page, chapter numbers, separators, draft chapters, the theme switcher, and whole-book PDF or EPUB output. The agent reports each one, along with any plugin it removed.

Upgrade your docs with Blume.

Install today and ship a production-grade docs site in minutes. Free and open source, forever.

npx blume init