Migration von GitBook

Migration von GitBook

bxSites migrate wandelt einen GitBook-Export - ein SUMMARY.md-Inhaltsverzeichnis plus dessen .md-Dateien, GitBooks eigenes Sync-Format auf der Festplatte (dasselbe, das GitHub/Git Sync schreibt) - mit einem Befehl in einen bx-sites-docs/-Baum um. Alles, was GitBooks Content-Block-System unterstützt, bildet auf etwas ab, das bx-sites bereits hat (siehe Content-Blöcke), das Ergebnis ist also kein grober Entwurf - es ist eine funktionierende Website.

Einen GitBook-Export beschaffen

bxSites migrate liest GitBooks eigenes Dateilayout direkt, sodass jedes der folgenden als --source funktioniert:

• Ein Repository, mit dem GitBook per Git-Sync verbunden ist (Space-Einstellungen → GitSync) - zeige --source auf deinen lokalen Clone.
• GitBooks eigener Export → Markdown-Download, entpackt.

So oder so sollte --source das Verzeichnis sein, das direkt SUMMARY.md enthält.

Die Migration ausführen

# 1. Scaffold a fresh bx-sites project (skip this if you already have one)
bxSites new my-docs
cd my-docs

# 2. Migrate the GitBook export into it
bxSites migrate --source=/path/to/gitbook-export

# 3. Build and look at the result
bxSites serve

migrate gibt aus, wie viele Seiten konvertiert wurden, und, wenn etwas eine Ermessensentscheidung erforderte, genau was und wo:

Migrated 14 page(s) from [/path/to/gitbook-export] into my-docs/docs/, wrote my-docs/docs/nav.json

2 item(s) need a manual look:
  - guides/advanced.md: Unsupported GitBook block [{% prompt %}] - left in its original syntax, needs manual conversion
  - guides/layout.md: Column width="one-third" is not a plain length/percentage - dropped, review manually

Nichts wird jemals stillschweigend verworfen - ein Block, den dieses Tool nicht zu konvertieren weiß, wird in der migrierten Datei in seiner ursprünglichen {% %}-Syntax belassen, der Inhalt ist also weiterhin vorhanden und leicht zu finden (durchsuche den migrierten docs/-Baum nach {%, wenn du fertig bist). Ein erneuter Lauf von migrate überschreibt jede Datei oder docs/nav.json, die er zuvor geschrieben hat, es ist also sicher, deinen Quell-Export zu korrigieren und es erneut auszuführen.

Was automatisch konvertiert wird

Ein Block, der in deinem GitBook-Inhalt als reines Beispiel in einem Fenced-Code-Block gezeigt wird (statt tatsächlich verwendet zu werden), wird korrekt in Ruhe gelassen und nicht als der echte Block missverstanden.

Was einen manuellen Blick braucht

Eine Handvoll GitBook-Blöcke hat überhaupt keine bx-sites-Entsprechung und wird in ihrer ursprünglichen {% %}-Syntax belassen, statt geraten zu werden: Prompt (ein KI-Generierungsblock - es gibt nichts, wogegen man ihn nach der Migration ausführen könnte), bedingter Inhalt (GitBook-Konto-basierte Sichtbarkeit, kein Konzept, das bx-sites hat), und die Ask-AI-Suchleiste. Alles andere, das dieses Tool nicht erkennt - ein vertippter Block, eine GitBook-Funktion, die nach der Entstehung dieses Tools hinzugefügt wurde - erhält dieselbe Behandlung: unverändert belassen, als Warnung gemeldet.

Ein paar kleinere Ermessensentscheidungen werden auf dieselbe Weise gemeldet: ein nicht erkannter hint-style (fällt auf note zurück), oder eine column-width, die keine reine CSS-Länge/-Prozentangabe ist (wird verworfen, statt wörtlich vertraut zu werden).

Seiten-Icons werden nicht automatisch migriert. GitBooks eigene Docs bestätigen nicht, dass die Icon-Zuweisung einer Seite (über den Icon-Picker des eigenen Editors gesetzt) einen Git-Sync-Export überhaupt übersteht - wenn die exportierte Frontmatter eines Projekts tatsächlich ein icon-Feld hat, übernimmt migrate es opportunistisch, erwarte das aber bei den meisten echten Exports nicht. Setze Icons stattdessen im Nachhinein von Hand - entweder in der eigenen Frontmatter einer Seite, oder im eigenen icon eines docs/nav.json-Eintrags

• mit einem benannten Icon aus einer der acht mitgelieferten Bibliotheken (es muss nicht zu GitBooks eigenen, Font-Awesome-basierten Icons passen; wähle einfach den Namen, der in der eigenen Galerie von Phosphor - in jeder seiner sechs Stärken - Lucide oder Tabler richtig aussieht).

Nach der Migration

Die migrierte docs/nav.json ist eine reine Nav-Override-Datei - bearbeite sie wie jede andere, oder lösche sie, um auf bx-sites' eigene Konvention Ordnerstruktur-ist-Navigationsstruktur zurückzufallen. Von hier an ist es ein normales bx-sites-Projekt: wähle ein Theme, überprüfe bxsites.json und deploye, sobald du zufrieden bist.