Zu Blume migrieren

Zieh eine Mintlify-, Docusaurus-, GitBook-, MkDocs-, ReadMe- oder eine andere Docs-Seite mit einem einzigen Befehl zu Blume um. Der Befehl übergibt die Migration an Codex oder Claude Code.

Eine Docs-Seite in idiomatisches Blume zu überführen, erfordert Entscheidungen, die ein Codemod nicht treffen kann. Welche deklarierte Navigation wird zu Ordnern? Welche Komponenten werden zu Direktiven? Was hat kein Gegenstück in Blume? Deshalb übergibt blume migrate die Aufgabe an einen Coding-Agent. Der arbeitet nach Blumes Migrations-Playbook, und du prüfst jede Änderung.

Mit einem Befehl migrieren

Führ den Befehl im Stammverzeichnis des Docs-Projekts aus, das du migrierst:

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

Ersetze fumadocs durch dein Framework. Wenn du Claude Code verwenden willst, ersetze --codex durch --claude. Mit pnpm 12 fügst du --allow-build=esbuild nach pnpm dlx hinzu, weil pnpm 12 das Installationsskript von esbuild nicht ohne Freigabe ausführt. Der Agent öffnet sich interaktiv in deinem Terminal, und jede Änderung durchläuft seinen eigenen Freigabeprozess. Er ändert die Dateien direkt in deinem Projekt. Starte deshalb mit einem sauberen Working Tree und prüfe die gesamte Migration als einen einzigen Diff.

Quellen

Gib das Framework an, von dem du migrierst. Wenn du es weglässt, erkennt Blume es anhand der Dateien im Projekt. Gibst du ein Framework an, das Projekt sieht aber nach einem anderen aus, warnt Blume dich und macht mit dem angegebenen weiter:

Quelle	Erkannt anhand von	Anleitung
`mintlify`	`docs.json` oder `mint.json`	Von Mintlify migrieren
`fumadocs`	`source.config.ts` oder `fumadocs-core`, `fumadocs-ui` oder `fumadocs-mdx` in `package.json`	Von Fumadocs migrieren
`docusaurus`	`docusaurus.config.*`	Von Docusaurus migrieren
`starlight`	`@astrojs/starlight` in `package.json`	Von Starlight migrieren
`nextra`	`nextra` in `package.json`	Von Nextra migrieren
`vitepress`	`.vitepress/config.ts` (oder `.mts`, `.js`, `.mjs`) im Stammverzeichnis oder in `docs/` oder `vitepress` in `package.json`	Von VitePress migrieren
`vuepress`	`.vuepress/config.ts` (oder `.js`, `.mjs`, `.yml`, `.toml`) im Stammverzeichnis oder in `docs/`, `vuepress.config.*` oder `vuepress` (oder `vuepress-vite`, `vuepress-webpack`) in `package.json`	Von VuePress migrieren
`docus`	`docus` (Docus 3 und neuer) oder `@nuxt-themes/docus` (Docus 1) in `package.json`; in einem Workspace führst du den Befehl im Docs-Paket aus	Von Docus migrieren
`mkdocs`	`mkdocs.yml`, `mkdocs.yaml`, `zensical.toml`, `properdocs.yml` oder `properdocs.yaml`	Von MkDocs Material migrieren
`mdbook`	`book.toml` im Stammverzeichnis oder in `docs/` oder `book/`	Von mdBook migrieren
`fern`	`fern/docs.yml`	Von Fern migrieren
`gitbook`	`.gitbook.yaml`, `.gitbook.yml` oder `gitbook-docs.yaml` oder `honkit` oder `gitbook-cli` in `package.json`; niemals nur anhand von `SUMMARY.md`	Von GitBook migrieren
`redocly`	`sidebars.yaml` oder `@redocly/realm` oder ein anderes Paket der Realm-Familie in `package.json`; niemals nur anhand von `redocly.yaml`	Von Redocly migrieren
`readme`	`_order.yaml` in `docs/`, `reference/`, `recipes/` oder `custom_pages/`; bei einem Repository, das mit `rdme` hochlädt, musst du die Quelle angeben	Von ReadMe migrieren
`docsify`	`docsify-cli` oder `docsify` in `package.json`; bei einer Seite ohne `package.json` musst du die Quelle angeben	Von Docsify migrieren
`jekyll`	`_config.yml` im Stammverzeichnis oder in `docs/`; wird erst nach allen anderen Quellen geprüft, die Blume erkennt	Von Just the Docs migrieren
`github-wiki`	Wird nie erkannt: Ein Wiki hat keine Konfigurationsdatei, deshalb musst du die Quelle angeben	Von einem GitHub-Wiki migrieren

Die Erkennung prüft den Ordner, in dem du den Befehl ausführst. Für jede Quelle gibt es im Playbook eine eigene Mapping-Referenz. Für mehrere Quellen gibt es außerdem einen Codemod, den der Agent zuerst für die mechanischen Umschreibungen ausführt. So kann er sich selbst auf die Ermessensentscheidungen konzentrieren. Auch eine Seite, die mit einem anderen Framework gebaut wurde, lässt sich migrieren. Führ den Befehl einfach ohne Quelle aus. Der Agent sieht sich dann zuerst an, was im Repo liegt, und arbeitet anschließend nach den allgemeinen Regeln des Playbooks.

Was der Agent macht

Der Agent folgt dem Workflow des Playbooks, von der Konfiguration der Quelle bis zu einem erfolgreichen Build:

Er schreibt blume.config.ts und überträgt dabei nur, was deine Quelle deklariert. Den Rest decken Blumes Standardwerte ab.
Er baut die Inhalte in eine Dateisystem-Navigation um und wandelt die Sortierdateien der einzelnen Ordner (Fumadocs meta.json, Nextra _meta) in meta.ts um.
Er schreibt die Seiten um: Frontmatter auf Blumes Schema, Callout-Komponenten zu Direktiven, Icons zu Lucide. Snippets fügt er direkt in die Seiten ein.
Er legt für jede URL, die sich ändert, eine Weiterleitung an, damit kein Link kaputtgeht. Die #/-URLs von Docsify erreichen nie den Server. Für diese fügt er deshalb ein kleines Skript hinzu, das jede davon auf ihre neue Seite weiterleitet. Die URLs eines GitHub-Wikis bleiben auf github.com, und dort sind keine Weiterleitungen möglich. Deshalb ordnet der Agent jede Seite ihrer neuen Route zu und bereitet Link-Stubs vor, die du ins alte Wiki pushen kannst.
Er stellt die Skripte in deiner package.json auf blume dev und blume build um und ersetzt die Abhängigkeiten des alten Frameworks durch blume.
Er führt blume build und blume validate so lange aus, bis beide ohne Fehler durchlaufen.

Zum Schluss fasst er zusammen, was er migriert, weggelassen oder nur annähernd umgesetzt hat. Das betrifft etwa Footer-Links oder Navbar-Buttons, für die es in Blume kein Gegenstück gibt. So kannst du bei jedem Punkt selbst entscheiden, wie du damit umgehst.

Andere Agents

Ohne --codex oder --claude meldet der Befehl nur die erkannte Quelle und gibt den Pfad zum Playbook aus. Das Playbook ist der Skill blume-migrate, der im Paket enthalten ist. Danach beendet sich der Befehl, ohne etwas zu ändern. Du kannst jeden anderen Agent auf diese SKILL.md verweisen. Oder du installierst den Skill mit dem ausgegebenen Befehl dort, wo dein Agent nach Skills sucht:

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

Zuerst vergleichen

Die Vergleichsseiten stellen Blume jedem Framework gegenüber. Dort steht auch, was die Migration jeweils übernimmt und was sie umschreibt.