Migrare da GitBook

Migrare da GitBook

bxSites migrate converte un export di GitBook - un sommario SUMMARY.md più i suoi file .md, il formato di sincronizzazione su disco proprio di GitBook (lo stesso scritto da GitHub/Git Sync) - in un albero docs/ di bx-sites, con un solo comando. Tutto ciò che il sistema di blocchi di contenuto di GitBook supporta corrisponde a qualcosa che bx-sites ha già (vedi Blocchi di contenuto), quindi il risultato non è una bozza approssimativa - è un sito funzionante.

Ottenere un export di GitBook

bxSites migrate legge direttamente la struttura di file propria di GitBook, quindi ognuna delle seguenti opzioni funziona come --source:

• Un repository a cui GitBook è sincronizzato via Git (impostazioni dello Space → GitSync) - punta --source al tuo clone locale.
• Il download Export → Markdown proprio di GitBook, decompresso.

In entrambi i casi, --source dovrebbe essere la cartella che contiene direttamente SUMMARY.md.

Eseguire la migrazione

# 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 stampa quante pagine ha convertito e, quando qualcosa ha richiesto una valutazione, esattamente cosa e dove:

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

Niente viene mai scartato in silenzio - un blocco che questo strumento non sa convertire viene lasciato nel file migrato nella propria sintassi originale {% %}, quindi il contenuto è comunque lì e ancora facile da trovare (cerca {% nell'albero docs/ migrato una volta finito). Rieseguire migrate sovrascrive qualsiasi file o docs/nav.json scritto in precedenza, quindi è sicuro correggere il proprio export sorgente ed eseguirlo di nuovo.

Cosa viene convertito automaticamente

Un blocco mostrato come esempio letterale delimitato nel tuo contenuto GitBook (invece di essere usato per davvero) viene correttamente lasciato stare, non frainteso per quello reale.

Cosa richiede un controllo manuale

Alcuni blocchi di GitBook non hanno alcun equivalente in bx-sites e vengono lasciati nella propria sintassi originale {% %} invece di essere indovinati: Prompt (un blocco di generazione AI - non c'è nulla contro cui eseguirlo una volta migrato), Contenuto condizionale (visibilità basata sull'account GitBook, un concetto che bx-sites non ha), e la barra di ricerca Ask AI. Qualsiasi altra cosa che questo strumento non riconosce - un blocco con un errore di battitura, una funzionalità di GitBook aggiunta dopo la scrittura di questo strumento - riceve lo stesso trattamento: lasciata così com'è, segnalata come avviso.

Alcune decisioni minori vengono segnalate allo stesso modo: uno style di hint non riconosciuto (ricade su note), oppure una width di column che non è una lunghezza/percentuale CSS semplice (scartata invece di essere presa alla lettera).

Le icone delle pagine non vengono migrate automaticamente. La documentazione stessa di GitBook non conferma che l'assegnazione dell'icona di una pagina (impostata tramite il selettore di icone del suo editor) sopravviva davvero in un export Git-Sync - se il frontmatter esportato di un progetto ha effettivamente un campo icon, migrate lo riporta opportunisticamente, ma non aspettartelo per la maggior parte degli export reali. Imposta le icone a mano in seguito - o nel frontmatter proprio di una pagina, oppure nell' icon di una voce di docs/nav.json - usando un'icona con nome da una delle otto librerie incluse (non serve far corrispondere le icone basate su Font Awesome proprie di GitBook; scegli qualunque nome sembri adatto nella galleria di Phosphor - uno qualsiasi dei suoi sei pesi - Lucide o Tabler).

Dopo la migrazione

Il docs/nav.json migrato è un normale file di nav esplicita - modificalo come qualsiasi altro, oppure eliminalo per ricadere sulla convenzione propria di bx-sites secondo cui la struttura delle cartelle è la struttura di navigazione. Da qui in poi è un normale progetto bx-sites: scegli un tema, rivedi bxsites.json, e distribuisci quando ne sei soddisfatto.