Blume vs MkDocs.MkDocs docs, with no Python to maintain.
Material for MkDocs is in maintenance mode, and MkDocs' last stable release is from August 2024. Blume builds in MDX components, API references, versioning, llms.txt, and an MCP server, with no Python environment or plugins to maintain, and an agent does the move.
npx blume migrate mkdocs --codex| Blume | MkDocs | |
|---|---|---|
| You maintain | BlumeA folder of Markdown, plus one optional config file | MkDocsmkdocs.yml, a Python environment, the Material theme, and plugins |
| License | BlumeFree and open source (MIT) | MkDocsFree and open source: MkDocs (BSD-2-Clause) and Material (MIT) |
| Components | BlumeMDX components like Tabs, Steps, Cards, and CodeGroup | MkDocsPython-Markdown extensions: admonitions, content tabs, grids, and annotations |
| Search | BlumeLocal search with no keys, or Pagefind, Algolia, and more by adapter | MkDocsBuilt-in client-side search with lunr, which also works offline |
| Agent features | Blumellms.txt, Markdown mirrors, and a JSON API by default; an opt-in MCP server | MkDocsllms.txt and Markdown copies through the third-party mkdocs-llmstxt plugin |
| API references | BlumeOpenAPI, AsyncAPI, and GraphQL, with a Try it playground | MkDocsPython and more through mkdocstrings; OpenAPI through community plugins |
| Versioning | Blumeblume version snapshots with a switcher and scoped search | MkDocsmike, an external tool that deploys each version through Git |
| Languages | Blumeblume translate fills in every locale with your coding agent | MkDocsTheme UI in 60+ languages; one build per language, or the static-i18n plugin |
MkDocs details are from its own pages as of October 7, 2026: Maintenance mode, Search, llms.txt plugin, mkdocstrings, Versioning, Languages. Something out of date? Let us know
Your docs come with you.A codemod converts the syntax, and an agent does the rest.
- Admonitions and tabs convert.
- A bundled codemod turns
!!!admonitions into:::directives,???blocks into Expandable, and content tabs into Tabs or a CodeGroup. - The nav moves into folders.
- The
navlist becomes folders andmeta.tsfiles, with group folders andslugpins where the old nesting kept URLs. - Plugins map to built-ins.
- Search, redirects, social cards, image zoom, the blog, git dates, and llmstxt become Blume config or are already built in.
- Old links keep working.
- The agent pins MkDocs' heading ids where Blume's differ, and turns every
redirect_mapsentry into a redirect.
MkDocs
Blume
- mkdocs.ymlblume.config.ts
- !!! note "Title":::note[Title]
- ??? tip "Title"<Expandable title="…">
- === "Tab"<Tab title="Tab">
- --8<-- "file.md"<include>
- { #id }[#id]
- hide: [toc]mode: wide
When MkDocs might suit you better.Blume isn't the right fit for every team.
- Your API reference comes from docstrings.
- mkdocstrings renders reference pages from Python source, with handlers for C, TypeScript, shell, and more. Blume has no docstring generator.
- You'd rather keep your setup.
- Zensical, from the Material for MkDocs team, reads
mkdocs.ymland builds existing projects, with replacements for popular plugins. If maintenance mode is your only concern, it's the smaller move. - You lean on Material's extras.
- Material renders code annotations and generates tag pages and blog archive and category pages. Blume has none of these, so the agent reports each one.
- 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 MkDocs to Blume.
Why move off MkDocs Material?
Material for MkDocs has been in maintenance mode since November 2025, fixing critical bugs but adding no features, and MkDocs' last stable release, 1.6.1, is from August 2024. Material's team also says the MkDocs 2.0 rewrite won't run Material. Blume builds in what MkDocs adds through plugins, like llms.txt, versioning, and API references, with no Python environment to maintain.
Can I keep my Markdown?
Yes. npx blume migrate mkdocs --codex opens an agent that runs a codemod over your pages, converting admonitions, content tabs, snippets, and heading ids and renaming only the pages that need MDX to .mdx. It then rebuilds nav as folders without changing a URL.
Should I move to Zensical instead?
If you want to keep your setup, Zensical is the smaller move: the Material for MkDocs team built it to read mkdocs.yml and build existing projects, though it hasn't reached 1.0 yet. Blume is the move if you want MDX components, OpenAPI, AsyncAPI, and GraphQL references with a Try it playground, and an MCP server, without a Python toolchain.
What happens to my mkdocstrings reference?
Blume doesn't generate references from Python docstrings, so the agent reports each mkdocstrings block. Keep that reference published where it is and link to it, or, for an HTTP API, let Blume build the reference from your OpenAPI spec.
What doesn't the migration carry over?
Output from mkdocstrings, mkdocs-click, and notebooks, macro functions and Jinja logic, template overrides and hooks with no layout slot, code annotations, tag index pages, and the blog's archive and category pages. The agent reports each one so you can decide what to do with it.
Upgrade your docs with Blume.
Install today and ship a production-grade docs site in minutes. Free and open source, forever.
npx blume init