GitBook ist eine beliebte Plattform zur Erstellung von Dokumentationsseiten, API-Guides und Wissensbanken mit Markdown. Wenn Ihre Dokumentationsentwürfe in Word live sind, ist die Konvertierung in GitBook-kompatible Markdown ein einfacher Prozess. Dieser Leitfaden umfaßt die vollständigen Word bis GitBook Arbeitsabläufe.
Warum GitBook für Dokumentation?
GitBook verwandelt Markdown-Dateien in eine ausgefeilte, durchsuchbare Dokumentationsseite mit:
- Ein sauberes, professionelles Standardthema
- Volltext-Suche
- Navigationsseitenleiste aus Ihrer Datei-Struktur erzeugt
- GitHub Synchronisierung für versionsgesteuerte Dokumente
- Benutzerdefinierte Domänen
Inhalte, die in Word geschrieben sind, passen sich nach GitBooks Seitenmodell, sobald sie in Markdown umgewandelt wurden, gut an.
Umwandlung von Word-Dokumenten
Beginnen Sie mit: WordToMD:
- Ziehen Sie Ihren .docx Dokumentationsentwurf auf den Konverter
- Überprüfen Sie die Markdown-Ausgabe Überschriften, Tabellen und Codeabschnitte überprüfen
- Herunterladen der .md-Datei
Die Ausgabe ist der Standard Markdown, den GitBook direkt akzeptiert.
GitBook Dateistruktur
GitBook organisiert Inhalte um eine SUMMARY.md Datei, die die Navigationsstruktur definiert:
# 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)Jede Kugel in SUMMARY.md wird zu einer Seite in Ihrer GitBook Seitenleiste. Nachdem Sie Ihre Word-Dokumente konvertiert haben, organisieren Sie sie in diese Struktur.
Vorgeschichte in GitBook
GitBook (Legacy-Versionen) verwendet keine YAML-Frontmatter Seitentitel stammen aus der ersten H1-Überschrift. GitBooks neuere Version (GitBook.com) akzeptiert einige Frontmatter, aber der sichere Ansatz ist es, die erste zu verwenden # Heading als Titel der Seite:
# Authentication Guide
This section describes how to authenticate with the API.
## Overview
...Aufbau der Leitung
GitBook erzeugt eine Inhaltstabelle auf Seitenebene aus den Überschriften H2 und H3. Halten Sie Ihre Hierarchie sauber:
- H1 Seitentitel (eine für jede Datei)
- H2 Hauptabschnitte (siehe Seite TOC)
- H3 Unterabschnitte
Sehen Sie Markdown Leitfaden für Überschriften für die Überschrift "Best Practices".
Tabellen in GitBook
GitBook stellt GFM-Tabellen mit Styling dar. Tabellen aus Ihrem Word-Dokument konvertieren korrekt über WordToMD:
| Endpoint | Method | Description |
|---|---|---|
| `/auth/login` | POST | Authenticate user |
| `/auth/logout` | POST | End session |
| `/users/{id}` | GET | Get user profile |Für komplexe Tabellenszenarien siehe Markdown Tabellen: Eine vollständige Anleitung.
Codeblöcke
GitBook stellt geschlossene Codeblöcke mit Syntax-Highlighting dar. Nach der Umwandlung mit WordToMD, die Codebeispiele ordnungsgemäß formatieren:
```bash
npm install -g gitbook-cli
gitbook init my-docs
```GitBook verfügt auch über einen speziellen Hint-Blocktyp für Aufrufe:
{% hint style="info" %}
This is an information callout.
{% endhint %}
{% hint style="warning" %}
This is a warning callout.
{% endhint %}Wenn in Ihrem Word-Dokument Kallout-Boxen markiert sind, konvertieren Sie diese nach der ersten Markdown-Konvertierung in GitBook-Hinweisblöcke.
GitHub Synchronisierungs-Arbeitsfluss
GitBook unterstützt die Synchronisierung mit einem GitHub-Repository:
- Erstellen Sie ein GitHub-Repo und fügen Sie Ihre konvertierten .md-Dateien hinzu
- Verbinden Sie GitBook mit dem Repo in GitBooks Einstellungen
- GitBook erstellt und veröffentlicht automatisch aus den Markdown-Dateien
- Bearbeitungen in GitBook synchronisiert zurück zu GitHub, und umgekehrt
Dadurch erhalten Sie Versionssteuerung für Ihre Dokumente und Ihr Team kann über GitHub PRs oder direkt im GitBook-Editor zusammenarbeiten.
Für GitHub Markdown-Spezifikationen siehe Word bis GitHub Markdown.
Bilder
Bilder aus Ihren Word Dokumenten exportieren (Save As → Webseite speichert Bilder in einen Ordner). In GitBook mit GitHub synchronisieren, die Bilder zu einem assets/ or images/ Verzeichnis und Verweise darauf:
In GitBooks Web-Editor können Sie Bilder direkt beim Bearbeiten von Seiten hochladen.
Übertragung eines vollständigen Dokumentationssets
Für eine große Dokumentationsmigration von Word zu GitBook:
- Prüfung der Word-Dokumente Identifizieren Sie Seiten, Abschnitte und Hierarchie
- Planen Sie die SUMMARY.md-Struktur vor der Umwandlung
- Dateien konvertieren with WordToMD (oder Umwandlung der Chargen für große Mengen)
- Erstellen von SUMMARY.md die mit Ihrer geplanten Struktur übereinstimmen
- Jede Seite überprüfen für Überschriftenhierarchie, Tabellenformatierung und Codeblöcke
- Veröffentlichen Über GitBooks Import oder GitHub Synchronisierung
FAQ
Welchen Markdown Geschmack verwendet GitBook? GitBook verwendet den Standard Markdown (CommonMark) und seine eigenen Erweiterungen (Hinweisblöcke, Registerkarten, Einbettblöcke). Die Markdown-Ausgabe von WordToMD ist kompatibel.
Kann ich ein .docx direkt in GitBook importieren? GitBook.coms Import-Funktion akzeptiert Word-Dokumente, aber die Ausgabe ist oft von niedrigerer Qualität als die Markdown. Der zweistufige Ansatz (Word → Markdown → GitBook) liefert für komplexe Dokumente bessere Ergebnisse.
Wie kann ich mit Dokumenten verknüpfen?
In GitBook mit GitHub Synchronisierung, verwenden Sie relative Markdown Links: [See Authentication](../api/authentication.md). GitBook resolves these to proper page links.
Meine Dokumentation hat mehr als 50 Word-Dateien. Gibt es einen schnelleren Arbeitsablauf? Sehen Sie Batch Konvertieren Word zu Markdown für die Automatisierung der Konvertierung Schritt, dann schreiben Sie ein Skript, um SUMMARY.md aus der Datei-Struktur zu generieren.
Schlußfolgerung
Umwandlung Word bis GitBook Markdown ist ein sauberer Arbeitsablauf: WordToMD Handhabt die Dokumentkonvertierung, und GitBooks GitHub Synchronisierung oder direkter Import handhabt die Veröffentlichung. Verwenden Sie Standard-Heading-Stile in Word, halten Sie Ihre Tabellen einfach, und Sie werden eine professionelle Dokumentationsseite haben, die schnell läuft.