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 | mdBook | |
|---|---|---|
| You maintain | BlumeA folder of Markdown, plus one optional config file | mdBookbook.toml, a hand-written SUMMARY.md, and each plugin's executable |
| Runtime | BlumeNode.js 22.19 or later | mdBookOne Rust binary, prebuilt for Windows, macOS, and Linux |
| License | BlumeFree and open source (MIT) | mdBookFree and open source (MPL-2.0) |
| Search | BlumeLocal search with no keys, or Pagefind, Algolia, and more by adapter | mdBookBuilt-in text search that runs in the browser |
| Code examples | BlumeHighlighted code blocks, not compiled or run | mdBookmdbook test compiles Rust samples, and a play button runs them |
| Agent features | Blumellms.txt, Markdown mirrors, and a JSON API by default; an opt-in MCP server | mdBookNot built in |
| Versioning | Blumeblume version snapshots with a switcher and scoped search | mdBookNot built in |
| Languages | Blumeblume translate fills in every locale with your coding agent | mdBookOne 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
.htmlURL, 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,ignoreare 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 testcompiles 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.
- 1
Run one command in your docs project.
Using Claude Code? Swap
--codexfor--claude. - 2
Review the agent's edits.
It follows Blume's migration playbook for MintlifyFumadocsDocusaurusStarlightNextraGitBookMkDocsReadMeVitePressFernRedoclyVuePressDocsifyDocusmdBookJekyllGitHub Wiki, rewriting your config and pages in place, so you review the whole move as one diff.
- 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