Migration von GitBook zu Docsbook: eine Schritt-für-Schritt-Anleitung

Sie sind an dem Punkt angelangt, an dem die nutzerabhängige Gebühr von GitBook schneller steigt als die Dokumentation. Oder der Preis für das KI-Add-on. Oder Sie haben bemerkt, dass Sie jährlich für eine Dokumentationsseite bezahlen, die nicht gut indexiert wird. Dies ist der praktische Migrationsleitfaden.

Die meisten Teams schließen die Migration in weniger als drei Stunden ab. Der aufwendige Teil sind die Weiterleitungen.

Kurzfassung#

1. GitBook-Inhalte als Markdown exportieren
2. In ein neues GitHub-Repository übertragen
3. Docsbook mit diesem Repository verbinden (5 Sekunden)
4. Die Website unter docsbook.io/yourorg/yourrepo überprüfen
5. Ihre benutzerdefinierte Domain docs.yourcompany.com mit Docsbook verknüpfen
6. Weiterleitungen von alten GitBook-Pfaden einrichten
7. Interne Links auf Ihrer Website aktualisieren

Schritt 1: Aus GitBook exportieren#

GitBook unterstützt den Markdown-Export über die Workspace-Einstellungen:

• Öffnen Sie Ihren GitBook-Bereich
• Einstellungen → Mit Git synchronisieren → „GitBook mit Git-Anbieter synchronisieren“
• Wählen Sie GitHub und anschließend ein neues privates oder öffentliches Repository aus
• GitBook synchronisiert Ihre Inhalte als Markdown mit Frontmatter

Alternative (ohne Git-Synchronisierung): Verwenden Sie die Option „In Markdown exportieren“ im Bereichsmenü und entpacken Sie das Ergebnis lokal.

Die Ordnerstruktur, die GitBook exportiert:

README.md
SUMMARY.md
docs/
  introduction.md
  guides/
    quick-start.md
  api/
    auth.md

Schritt 2: An die Docsbook-Konventionen anpassen#

Zwei kleine Unterschiede, die berücksichtigt werden müssen:

SUMMARY.md ist in Docsbook optional#

GitBook verwendet SUMMARY.md als Navigationsquelle. Docsbook erstellt die Navigation automatisch aus Ihrer Ordnerstruktur und dem Frontmatter title.

Sie können SUMMARY.md beibehalten (Docsbook ignoriert es) oder löschen. Die meisten Teams löschen es.

Frontmatter#

GitBook-Frontmatter:

---
description: How to authenticate
---

Docsbook liest dasselbe Feld description sowie optional title. Falls title fehlt, wird die erste H1-Überschrift verwendet.

Ein einfaches Migrationsskript:

find . -name "*.md" -not -path "./.git/*" -exec \
  sed -i.bak '1,/^---$/ s/^description:/description:/' {} \;

(In den meisten Fällen sind keine Änderungen erforderlich – GitBook- und Docsbook-Frontmatter sind kompatibel.)

Schritt 3: Docsbook verbinden#

• Gehe zu docsbook.io
• Melde dich mit GitHub an
• Füge github.com/yourorg/yourrepo ein
• Die Website ist in 5 Sekunden unter docsbook.io/yourorg/yourrepo live

Wenn dein Repository den Ordner docs/ enthält, verwendet Docsbook ihn. Wenn deine Dokumentation im Stammverzeichnis liegt, funktioniert das ebenfalls.

Schritt 4: Benutzerdefinierte Domain#

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

Im Docsbook-Dashboard:

• Einstellungen → Domain
• docs.yourcompany.com eingeben
• DNS aktualisieren: CNAME docs → cname.vercel-dns.com
• SSL ist automatisch und kostenlos

Schritt 5: Die Weiterleitungen#

Dies ist der einzige für SEO relevante Schritt. GitBook-URLs sehen so aus:

docs.yourcompany.com/v/1.0/api/authentication

Docsbook-URLs:

docs.yourcompany.com/api/authentication

Sie haben zwei Möglichkeiten:

Option A: Weiterleitung auf DNS/CDN-Ebene#

Wenn Cloudflare vor Ihrer Domain geschaltet ist, fügen Sie Seitenregeln hinzu:

docs.yourcompany.com/v/*/api/* → docs.yourcompany.com/api/$2 [301]

Option B: Weiterleitung über Docsbook#

Füge eine _redirects-Datei (falls dein Stack dies unterstützt) im Stammverzeichnis deines Repositorys hinzu:

/v/1.0/api/auth /api/auth 301
/v/1.0/api/webhooks /api/webhooks 301

Eine 301-Weiterleitung erhält die SEO-Autorität. Eine 302-Weiterleitung tut dies nicht – verwende 301.

Schritt 6: Interne Verweise aktualisieren#

Durchsuchen und ersetzen Sie in Ihrer Codebasis:

grep -rl "docs.yourcompany.com/v/" . | xargs sed -i.bak 's|docs.yourcompany.com/v/[0-9.]*/|docs.yourcompany.com/|g'

Aktualisieren Sie:

• Den Fußzeilenlink Ihrer Produkt-App
• Ihre Marketing-Website
• Ihre README-Links auf GitHub
• Die gespeicherten Antworten Ihres Support-Teams

Schritt 7: Die KI-Oberfläche überprüfen#

Docsbook generiert llms.txt, llms-full.txt, JSON-LD und die Sitemap automatisch. Überprüfen Sie:

curl https://docs.yourcompany.com/llms.txt | head -20
curl https://docs.yourcompany.com/sitemap.xml | head -10

Weitere Informationen finden Sie unter llms.txt: der vollständige Leitfaden.

Was wird besser#

Was könnte kaputtgehen#

• GitBook-spezifische Blöcke — aufklappbare Abschnitte, Hinweisblöcke, Tabs. Docsbook unterstützt Standard-Markdown sowie Docsbook-spezifische Blöcke. Die meisten GitBook-Hinweise lassen sich problemlos in > [!NOTE]-Hinweise umwandeln.
• Benutzerdefinierte OpenAPI-Integration — GitBook verfügt über einen Renderer für API-Referenzen. Docsbook rendert OpenAPI über Ihre vorhandenen Tools oder verweist nach außen.
• GitBook-KI-Chatverlauf — wird nicht übertragen. Der Chat beginnt mit Ihren neuen Inhalten von vorn.

Zeitaufwand#

Nach unserer Erfahrung bei der Unterstützung von Teams bei der Migration:

• Einzelgründer, ca. 50 Seiten: 1 Stunde
• Kleines Startup, ca. 200 Seiten: 3 Stunden
• Unternehmen in der Wachstumsphase, ca. 1000 Seiten, eigene Domain: ein halber Tag

Der aufwendige Teil besteht darin, die URL-Änderung intern bekannt zu machen und gespeicherte Antworten in Ihrem Support-Tool zu aktualisieren.

Kostenlos starten — keine Kreditkarte

Nächste Schritte#

• GitBook vs. Docsbook — der Funktionsvergleich hinter diesem Wechsel
• Benutzerdefinierte Domain für die Dokumentation — die DNS- und SSL-Hälfte von Schritt 4
• SEO-Leitfaden für Dokumentationen — so bleiben Ihre Rankings beim Ändern der URLs erhalten