GitBook è una piattaforma popolare per la creazione di siti di documentazione, guide API e basi di conoscenza utilizzando Markdown. Se i progetti di documentazione vivono in Word, convertirli in GitBook-compatibile Markdown è un processo semplice. Questa guida copre l'intero Word a GitBook flusso di lavoro.
Perché GitBook per la documentazione?
GitBook trasforma i file Markdown in un sito di documentazione rifinito e consultabile con:
- Un tema predefinito pulito e professionale
- Ricerca a testo completo
- Barra laterale di navigazione generata dalla struttura del file
- GitHub sincronizzazione per i documenti controllati dalle versioni
- Domeni personalizzati
I contenuti scritti in Word mappano bene al modello di pagina di GitBook una volta convertiti in Markdown.
Convertire documenti Word
Inizia con WordToMD:
- Trascinare il progetto di documentazione .docx sul convertitore
- Riesaminare l'uscita Markdown controllare titoli, tabelle e sezioni di codice
- Scarica il file .md
L'uscita è Markdown standard che GitBook accetta direttamente.
GitBook Struttura del file
GitBook organizza i contenuti intorno a SUMMARY.md file che definisce la struttura di navigazione:
# Table of Contents
* [Introduction](README.md)
* [Getting Started](getting-started/README.md)
* [Installation](getting-started/installation.md)
* [Configuration](getting-started/configuration.md)
* [API Reference](api/README.md)
* [Authentication](api/authentication.md)Ogni proiettile in SUMMARY.md diventa una pagina nella tua barra laterale GitBook. Dopo aver convertito i documenti Word, organizzarli in questa struttura.
La prima pagina di GitBook
GitBook (versioni precedenti) non utilizza il frontmatter YAML i titoli delle pagine provengono dal primo titolo H1. GitBook's versione più recente (GitBook.com) accetta alcuni elementi di fronte, ma l'approccio sicuro è quello di utilizzare il primo # Heading come titolo della pagina:
# Authentication Guide
This section describes how to authenticate with the API.
## Overview
...Struttura delle rubriche
GitBook genera una tabella dei contenuti a livello di pagina da intestazioni H2 e H3. Mantenete la vostra gerarchia pulita:
- H1 Titolo della pagina (uno per file)
- H2 Sezioni principali (appare nella pagina TOC)
- H3 Sottosezioni
Vede la tabella Markdown Guida delle rubriche per le migliori pratiche.
Tabelle in GitBook
GitBook rende le tabelle GFM con lo stile. Tavole dal tuo documento Word convertire correttamente via WordToMD:
| Endpoint | Method | Description |
|---|---|---|
| `/auth/login` | POST | Authenticate user |
| `/auth/logout` | POST | End session |
| `/users/{id}` | GET | Get user profile |Per gli scenari complessi delle tabelle, vedere Markdown Tabelle: una guida completa.
Blocchi di codice
GitBook rende blocchi di codice recintati con sintassi evidenziata. Dopo la conversione con WordToMD, formattare correttamente i campioni di codice:
```bash
npm install -g gitbook-cli
gitbook init my-docs
```GitBook ha anche uno speciale tipo di blocco Hint per le chiamate:
{% hint style="info" %}
This is an information callout.
{% endhint %}
{% hint style="warning" %}
This is a warning callout.
{% endhint %}Se il tuo documento Word ha evidenziato le caselle di chiamata, convertirli in blocchi di suggerimento GitBook dopo la conversione iniziale Markdown.
GitHub Flusso di lavoro di sincronizzazione
GitBook supporta la sincronizzazione con un repository GitHub:
- Creare un GitHub repo e aggiungere i file convertiti .md
- Collegare GitBook al repo nelle impostazioni di GitBooks
- GitBook crea e pubblica automaticamente dai file Markdown
- Modifiche in GitBook sincronizzare di nuovo a GitHub, e viceversa
Questo ti dà il controllo delle versioni per i tuoi documenti e consente al tuo team di collaborare tramite GitHub PR o direttamente nell'editor di GitBook.
Per le specifiche GitHub Markdown, vedere Word a GitHub Markdown.
Immagini
Esporta le immagini dai tuoi documenti Word (Salva come → Pagina Web salva le immagini in una cartella). In GitBook con GitHub sincronizzazione, impegnare le immagini a un assets/ or images/ directory e fare riferimento a questi:
Nell'editor web di GitBook, è possibile caricare immagini direttamente quando si modificano le pagine.
Migratura di un set di documentazione completo
Per una migrazione di documentazione di grandi dimensioni da Word a GitBook:
- Verifica dei documenti Word identificare le pagine, le sezioni e la gerarchia
- Pianificare la struttura SUMMARY.md prima della conversione
- Convertire file with WordToMD (o conversione di lotti per grandi volumi)
- Creare SUMMARY.md corrispondente alla struttura prevista
- Rivedi ogni pagina per la gerarchia delle intestazioni, la formattazione delle tabelle e i blocchi di codice
- Pubblicare tramite GitBooks import o GitHub sincronizzazione
FAQ
Quale sapore Markdown usa GitBook? GitBook utilizza Markdown (CommonMark) standard più le sue estensioni (blocchi di suggerimento, schede, blocchi di inserimento). L'uscita Markdown da WordToMD è compatibile.
Posso importare un .docx direttamente in GitBook? GitBook.com's import feature accetta Word documenti, ma l'output è spesso di qualità inferiore rispetto a passare attraverso Markdown. L'approccio a due fasi (Word → Markdown → GitBook) dà risultati migliori per documenti complessi.
Come faccio a gestire i collegamenti tra i documenti?
In GitBook con GitHub sincronizzazione, utilizzare collegamenti relativi Markdown: [See Authentication](../api/authentication.md). GitBook resolves these to proper page links.
La mia documentazione contiene più di 50 file Word. C'e' un flusso di lavoro piu' veloce? Vede la tabella Batch Convertire Word a Markdown per automatizzare il passaggio di conversione, quindi scrivere uno script per generare SUMMARY.md dalla struttura del file.
Conclusioni
Conversione Word a GitBook Markdown è un flusso di lavoro pulito: WordToMD gestisce la conversione del documento e GitBooks GitHub sincronizzazione o importazione diretta gestisce la pubblicazione. Utilizzare gli stili standard di intestazione in Word, mantenere le tabelle semplici, e avrai un sito di documentazione professionale in esecuzione veloce.