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

Migrate to Blume

Move a Mintlify, Docusaurus, GitBook, MkDocs, ReadMe, or other docs site to Blume with one command that hands the migration to Codex or Claude Code.

Moving a docs site to idiomatic Blume takes judgment a codemod can’t make: which declared navigation becomes folders, which components become directives, and what has no Blume equivalent. So blume migrate hands the job to a coding agent, working from Blume’s migration playbook, while you review each edit.

Migrate with one command

Run it from the root of the docs project you’re migrating:

npx blume migrate fumadocs --codex
pnpm dlx blume migrate fumadocs --codex
yarn dlx blume migrate fumadocs --codex
bunx blume migrate fumadocs --codex
nubx blume migrate fumadocs --codex
aube dlx blume migrate fumadocs --codex

Swap fumadocs for your framework, and --codex for --claude to use Claude Code. With pnpm 12, add --allow-build=esbuild after pnpm dlx, since pnpm 12 won’t run esbuild’s install script unapproved. The agent opens interactively in your terminal, so every edit goes through its own permission flow. It works in place, so start from a clean working tree and review the whole migration as one diff.

Sources

Name the framework you’re migrating from, or leave it out and Blume detects it from the project’s own files. When you name one and the project looks like another, Blume warns and continues with the one you named:

Source Detected from Guide
mintlify docs.json or mint.json Migrate from Mintlify
fumadocs source.config.ts, or fumadocs-core, fumadocs-ui, or fumadocs-mdx in package.json Migrate from Fumadocs
docusaurus docusaurus.config.* Migrate from Docusaurus
starlight @astrojs/starlight in package.json Migrate from Starlight
nextra nextra in package.json Migrate from Nextra
vitepress .vitepress/config.ts (or .mts, .js, .mjs) at the root or in docs/, or vitepress in package.json Migrate from VitePress
vuepress .vuepress/config.ts (or .js, .mjs, .yml, .toml) at the root or in docs/, vuepress.config.*, or vuepress (or vuepress-vite, vuepress-webpack) in package.json Migrate from VuePress
docus docus (Docus 3 and later) or @nuxt-themes/docus (Docus 1) in package.json; run it from the docs package in a workspace Migrate from Docus
mkdocs mkdocs.yml, mkdocs.yaml, zensical.toml, properdocs.yml, or properdocs.yaml Migrate from MkDocs Material
mdbook book.toml at the root or in docs/ or book/ Migrate from mdBook
fern fern/docs.yml Migrate from Fern
gitbook .gitbook.yaml, .gitbook.yml, or gitbook-docs.yaml, or honkit or gitbook-cli in package.json; never SUMMARY.md alone Migrate from GitBook
redocly sidebars.yaml, or @redocly/realm or another Realm-family package in package.json; never redocly.yaml alone Migrate from Redocly
readme _order.yaml in docs/, reference/, recipes/, or custom_pages/; a repository that uploads with rdme needs the source named Migrate from ReadMe
docsify docsify-cli or docsify in package.json; a site without a package.json needs the source named Migrate from Docsify
jekyll _config.yml at the root or in docs/, checked after every other source Blume detects Migrate from Just the Docs
github-wiki Never detected: a wiki has no config file, so name the source Migrate from a GitHub wiki

Detection checks the folder you run the command in. Each source has its own mapping reference in the playbook, and several also have a codemod the agent runs first for the mechanical rewrites, so its own effort goes to the judgment calls. A site built with anything else still migrates: run the command without a source, and the agent inventories the repo first, then works from the playbook’s general rules.

What the agent does

The agent follows the playbook’s workflow from the source’s config to a passing build:

  1. Writes blume.config.ts, mapping only what your source declares and leaving Blume’s defaults to cover the rest.
  2. Restructures content into filesystem navigation, converting per-folder ordering files (Fumadocs meta.json, Nextra _meta) to meta.ts.
  3. Rewrites pages: frontmatter to Blume’s schema, callout components to directives, icons to Lucide, and snippets inlined.
  4. Adds a redirect for every URL that moves, so no link breaks. Docsify’s #/ URLs never reach the server, so for those it adds a small script that sends each one to its new page. A GitHub wiki’s URLs stay on github.com, which can’t redirect, so the agent maps each page to its new route and prepares link stubs you can push to the old wiki.
  5. Points your package.json scripts at blume dev and blume build, and swaps the old framework’s dependencies for blume.
  6. Runs blume build and blume validate until both pass.

It finishes with a summary of what it migrated, dropped, or approximated, such as footer links or navbar buttons with no Blume equivalent, so you can decide what to do with each.

Other agents

Without --codex or --claude, the command reports the source it detected, prints the path to the playbook — the blume-migrate skill bundled in the package — and exits without changing anything. Point any other agent at that SKILL.md, or install the skill where your agent looks for skills, with the command it prints:

npx skills add haydenbleasel/blume --skill blume-migrate

Compare first

The comparison pages set Blume beside each framework and list what the migration carries over and rewrites for it.

Last updated on

Was this page helpful?