Migration von Docusaurus zu Docsbook

Docusaurus ist großartig, bis die nächste große Migration ansteht und Sie einen Sprint dafür aufwenden, anstatt das Produkt zu versenden. Dieser Leitfaden beschreibt den realistischen Migrationspfad.

Wir machen Docsbook. Wir werden Ihnen auch sagen, wann eine Migration nicht lohnenswert ist.

Wann Sie nicht migrieren sollten#

Überspringen Sie diese Migration, wenn:

• Ihre Docusaurus-Website verwendet umfangreiche React-Komponenten-Einbettungen (interaktive Demos, benutzerdefinierte Plugins). Docsbook ist markdown-first.
• Sie haben einen dedizierten Dokumentationsingenieur, dessen Aufgabe teilweise Docusaurus umfasst. Die Plattform hat in ihren Händen echte Stärken.
• Sie benötigen ein tiefgehend angepasstes React-Theme. Docsbook bietet Ihnen Farb-Tokens, Schriftarten, Layout-Wechsel, Header-/Footer-Konfiguration — nicht vollständige Theme-Anpassungen.

Wenn eines davon zutrifft, bleiben Sie bei Docusaurus und lesen Sie den Rest dieses Leitfadens später.

TL;DR#

1. MDX-spezifische Syntax in Standard-Markdown umwandeln
2. In ein GitHub-Repo pushen (du hast bereits eines)
3. Docsbook verbinden
4. Benutzerdefinierte Domain einrichten
5. Weiterleitungen portieren
6. Die CI-Pipeline und die Hosting-Kosten streichen

Schritt 1: MDX zu Markdown#

Docusaurus verwendet MDX, das ist Markdown + JSX. Docsbook verwendet standardmäßiges Markdown mit Erweiterungen.

Drei Klassen von MDX, die behandelt werden müssen:

Importe und React-Komponenten#

import Foo from '@site/src/components/Foo';
 
<Foo />

Lösungen:

• Für statische Visuals: ersetzen Sie es durch ein gehostetes Bild und einen Link zu einer Live-Demo
• Für interaktive Elemente: verlinken Sie zu Ihrer App
• Für Tabs/Anweisungen: verwenden Sie die nativen Blöcke von Docsbook (siehe unten)

Hinweise#

Docusaurus:

:::note Title
Content
:::

Docsbook (GitHub-aromatisiertes Markdown):

> [!NOTE]
> Content

Finden und Ersetzen:

find . -name "*.mdx" -exec rename 's/\.mdx$/\.md/' {} \;
find . -name "*.md" -exec sed -i.bak -E 's/:::note/> [!NOTE]/g; s/:::tip/> [!TIP]/g; s/:::warning/> [!WARNING]/g; s/:::caution/> [!CAUTION]/g; s/:::info/> [!NOTE]/g; s/^:::$//' {} \;

Tabs und Codegruppen#

Docsbook unterstützt Tabs über eine standardisierte Syntax:

<Tabs>
  <Tab title="npm">npm install foo</Tab>
  <Tab title="pnpm">pnpm add foo</Tab>
</Tabs>

Die meisten Docusaurus-Tabs übersetzen sich eins zu eins.

Schritt 2: Seitenleiste und Navigation#

Docusaurus verwendet sidebars.js, um die Navigation zu definieren. Docsbook erstellt die Navigation aus Ihrer Ordnerstruktur und dem Frontmatter.

Wenn Sie eine bestimmte Reihenfolge wünschen:

---
title: "Quick Start"
order: 1
---

Wenn Sie keine Reihenfolge angeben, sortiert Docsbook alphabetisch. Verschieben Sie Dateien in geordnete Ordner, wenn Sie eine explizite Gruppierung benötigen.

Sie können sidebars.js, docusaurus.config.js, babel.config.js und das src/ Verzeichnis nach der Migration löschen.

Schritt 3: Docsbook verbinden#

Ihre Dokumente sind bereits in docs/. Verbinden Sie einfach:

• docsbook.io → Mit GitHub anmelden
• Fügen Sie github.com/yourorg/yourrepo ein
• Website live unter docsbook.io/yourorg/yourrepo

Schritt 4: Benutzerdefinierte Domain#

PRO (150 $ einmalig) oder PRO+ (59 $/Monat) umfasst eine benutzerdefinierte Domain.

• Docsbook-Dashboard → Einstellungen → Domain
• Geben Sie docs.yourcompany.com ein
• DNS aktualisieren: CNAME docs → cname.vercel-dns.com
• Warten Sie 5 Minuten auf SSL

Schritt 5: URL-Erhaltung#

Docusaurus-URLs sehen typischerweise so aus:

docs.yourcompany.com/docs/intro
docs.yourcompany.com/docs/category/guides/getting-started

Docsbook-URLs entsprechen Ihren Dateipfaden:

docs.yourcompany.com/intro.md → docs.yourcompany.com/intro
docs.yourcompany.com/guides/getting-started.md → docs.yourcompany.com/guides/getting-started

Wenn Ihr Docusaurus ein /docs/ Präfix hatte und Sie die Parität beibehalten möchten:

Option A: benennen Sie den lokalen docs/ Ordner um, um das Präfix in den URLs beizubehalten (Docsbook wird von einem anderen Pfad aus bereitgestellt).

Option B: fügen Sie Weiterleitungen von alten /docs/* URLs zu neuen /* URLs auf Ihrer CDN- oder DNS-Ebene hinzu.

Schritt 6: CI/CD ablegen#

Sobald Docsbook Traffic bedient:

# Files you can delete
rm -rf .docusaurus/
rm -rf build/
rm -rf node_modules/
rm docusaurus.config.js
rm sidebars.js
rm babel.config.js
rm -rf src/
rm -rf static/
# Keep docs/ — it is your source

GitHub Actions Workflow-Datei für Docusaurus-Bereitstellung: ebenfalls löschen.

Das Ergebnis: Docs werden bei jedem git push auf main bereitgestellt, keine CI-Minuten verwendet.

Was Sie gewinnen#

Was Sie aufgeben#

• React-Komponenten-Embed in Dokumenten (woanders hosten, verlinken)
• Vollständige Kontrolle über das Swizzle-Theme (Sie erhalten Farb-/Schrift-/Layout-Token)
• Plugin-Ökosystem (die meisten Fälle sind bereits integriert)

Grenzfälle#

Algolia DocSearch#

Sie können Algolia DocSearch weiterhin auf Docsbook verwenden (richten Sie es auf Ihre neue Domain aus). Oder verwenden Sie die integrierte Suche von Docsbook, die kostenlos enthalten ist.

Benutzerdefinierte Landing-Page#

Docusaurus hat oft eine benutzerdefinierte Landing-Page unter /, die in React erstellt wurde. Docsbook bedient Ihr README.md unter /. Wenn Sie eine marketingorientierte Landing-Page möchten, hosten Sie diese separat und verweisen Sie Docsbook auf docs.yourcompany.com anstelle von yourcompany.com.

Versionierung#

Das docs/versioned_docs/version-1.0/ Muster von Docusaurus wird nicht direkt unterstützt. Optionen:

• Verwenden Sie separate Docsbook-Arbeitsbereiche pro Version (docsbook.io/yourorg/yourrepo-v1)
• Verwenden Sie Git-Zweige und wechseln Sie den indizierten Zweig
• Alte Versionen fallen lassen (die meisten Teams stellen fest, dass sie diese aus Gewohnheit gepflegt haben)

Zeitplanung#

• OSS-Projekt, ~80 Seiten, minimales MDX: 2 Stunden
• Startup, ~300 Seiten, moderates MDX: einen halben Tag
• Mid-Stage, ~1000 Seiten, intensives MDX: 1–2 Tage

Verwandte Lektüre#

• Docusaurus vs Docsbook im Jahr 2026
• Docs als Code vs verwaltete Plattform
• Benutzerdefinierte Domain für Dokumentationen - Anleitung

Testen Sie zuerst die Migration: Fügen Sie Ihr Repository unter docsbook.io ein. Die Seite wird in 5 Sekunden erstellt. Wenn es nicht mit Ihrer Docusaurus-Parität übereinstimmt, haben Sie nichts verloren.