Schritt für Schritt von Docusaurus zu Docsbook migrieren

Docusaurus ist großartig, bis die nächste größere Migration ansteht und du einen Sprint damit verbringst, statt das Produkt auszuliefern. Dieser Leitfaden führt durch den realistischen Migrationspfad.

Wir entwickeln Docsbook. Wir sagen dir auch, wann sich eine Migration nicht lohnt.

Wann Sie nicht migrieren sollten#

Überspringen Sie diese Migration, wenn:

Ihre Docusaurus-Website umfangreiche Einbettungen von React-Komponenten verwendet (interaktive Demos, benutzerdefinierte Plugins). Docsbook ist auf Markdown ausgerichtet.
Sie einen dedizierten Dokumentationsentwickler haben, zu dessen Aufgaben teilweise auch Docusaurus gehört. Die Plattform hat in den Händen eines solchen Entwicklers echte Stärken.
Sie ein stark individualisiertes React-Theme benötigen. Docsbook bietet Farb-Token, Schriftarten, Layout-Umschalter sowie Konfigurationen für Header und Footer – aber kein vollständiges Theme-Swizzling.

Wenn einer dieser Punkte zutrifft, bleiben Sie bei Docusaurus und lesen Sie den Rest dieses Leitfadens später.

Kurz gesagt#

MDX-spezifische Syntax in Standard-Markdown umwandeln
In ein GitHub-Repository pushen (du hast bereits eines)
Docsbook verbinden
Eine benutzerdefinierte Domain einrichten
Weiterleitungen übernehmen
Die CI-Pipeline und die Hostingkosten abschaffen

Schritt 1: MDX zu Markdown#

Docusaurus verwendet MDX, eine Kombination aus Markdown und JSX. Docsbook verwendet Standard-Markdown mit Erweiterungen.

Drei Kategorien von MDX müssen behandelt werden:

Imports und React-Komponenten#

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

Lösungen:

Für statische Visualisierungen: durch ein gehostetes Bild und einen Link zu einer Live-Demo ersetzen
Für interaktive Elemente: auf Ihre App verlinken
Für Tabs/Admonitions: die nativen Blöcke von Docsbook verwenden (siehe unten)

Hinweise#

Docusaurus:

:::note Title
Content
:::

Docsbook (GitHub-kompatibles Markdown):

> [!NOTE]
> Content

Suchen 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/^:::$//' {} \;

Registerkarten und Codegruppen#

Docsbook unterstützt Registerkarten über eine Standardsyntax:

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

Die meisten Docusaurus-Registerkarten lassen sich eins zu eins übertragen.

Docusaurus verwendet sidebars.js, um die Navigation zu definieren. Docsbook erstellt die Navigation anhand Ihrer Ordnerstruktur und des Frontmatters.

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 Verzeichnis src/ nach der Migration löschen.

Schritt 3: Docsbook verbinden#

Ihre Dokumentation befindet sich bereits in docs/. Verbinden Sie das Repository:

docsbook.io → Mit GitHub anmelden
github.com/yourorg/yourrepo einfügen
Website live unter docsbook.io/yourorg/yourrepo

Schritt 4: Benutzerdefinierte Domain#

Docsbook stellt docs.yourcompany.com mit automatischem SSL bereit.

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 Konsistenz beibehalten möchten:

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

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

Schritt 6: CI/CD abschaffen#

Sobald Docsbook den Datenverkehr verarbeitet:

# 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

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

Das Ergebnis: Die Dokumentation wird bei jedem git push auf main bereitgestellt, ohne CI-Minuten zu verbrauchen.

Ihr Nutzen#

	Docusaurus	Docsbook
Build-Zeit	30–120 Sekunden pro Push	Insgesamt 5 Sekunden Einrichtung
Hosting-Kosten	Vercel-/Netlify-Pro-Tarif	Inklusive
KI-Chat	Plugin-Entwicklung	Integriert
Übersetzungen	Konfiguration pro Sprache + Übersetzungspipeline	Integriert, 15 Sprachen
Migrationen größerer Versionen	Alle 18 Monate	Niemals
Theme-Wartung	Swizzle-Drift	Farb-Tokens, keine Wartung

Was Sie aufgeben#

Einbettungen von React-Komponenten in Dokumentationen (hosten Sie sie an anderer Stelle und verlinken Sie darauf)
Vollständige Kontrolle über das Swizzle-Theme (Sie erhalten Farb-, Schriftart- und Layout-Token)
Plugin-Ökosystem (die meisten Fälle sind bereits integriert)

Sonderfälle#

Algolia DocSearch#

Du kannst Algolia DocSearch weiterhin auf Docsbook verwenden (richte es auf deine neue Domain). Oder verwende die integrierte Suche von Docsbook, die kostenlos enthalten ist.

Individuelle Landingpage#

Docusaurus verfügt häufig über eine individuelle Landingpage bei /, die in React erstellt wurde. Docsbook stellt Ihre README.md unter / bereit. Wenn Sie eine Landingpage im Marketing-Stil wünschen, hosten Sie diese separat und verweisen Sie Docsbook stattdessen 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:

Separate Docsbook-Arbeitsbereiche pro Version verwenden (docsbook.io/yourorg/yourrepo-v1)
Git-Branches verwenden und den indexierten Branch wechseln
Alte Versionen entfernen (die meisten Teams stellen fest, dass sie diese aus Gewohnheit gepflegt haben)

Zeitaufwand#

OSS-Projekt, ~80 Seiten, minimales MDX: 2 Stunden
Start-up, ~300 Seiten, moderates MDX: ein halber Tag
Unternehmen in der mittleren Phase, ~1000 Seiten, umfangreiches MDX: 1–2 Tage

Testen Sie die Migration, bevor Sie sich dafür entscheiden. Das Veröffentlichen einer zweiten Website aus demselben Repository kostet nichts und ändert nichts an der Docusaurus-Bereitstellung, über die Ihre Leser weiterhin versorgt werden – wenn das Ergebnis nicht gleichwertig ist, haben Sie lediglich die fünf Sekunden verloren, die dafür nötig waren.

Kostenlos starten – keine Kreditkarte erforderlich

Nächste Schritte#

Sollten Sie Docusaurus im Jahr 2026 den Rücken kehren? — die Entscheidung, falls Sie sie noch nicht getroffen haben
Docusaurus-Alternativen im Jahr 2026: 9 Plattformen im Vergleich — das weitere Feld
Benutzerdefinierte Domain für die Dokumentation — die DNS- und Weiterleitungshälfte dieser Migration
Docs as Code oder eine verwaltete Plattform — das Prinzip hinter dem Wechsel