GitBook est une plateforme populaire pour créer des sites de documentation, des guides API et des bases de connaissances en utilisant Markdown. Si vos ébauches de documentation sont en Word, les convertir en GitBook-compatible Markdown est un processus simple. Ce guide couvre l'ensemble des Word à GitBook le flux de travail.
Pourquoi GitBook pour la documentation ?
GitBook transforme les fichiers Markdown en un site de documentation raffiné et consultable avec:
- Un thème par défaut propre et professionnel
- Recherche en texte intégral
- Barre latérale de navigation générée à partir de votre structure de fichier
- GitHub synchronisation pour les documents contrôlés par version
- Domaines personnalisés
Le contenu écrit en Word correspond bien au modèle de page de GitBook une fois converti en Markdown.
Conversion de documents Word
Commencez par WordToMD:
- Faites glisser votre projet de documentation .docx sur le convertisseur
- Examiner la sortie Markdown vérifier les rubriques, les tableaux et les sections de code
- Télécharger le fichier .md
La sortie est standard Markdown que GitBook accepte directement.
GitBook Structure du fichier
GitBook organise le contenu autour d'un SUMMARY.md fichier qui définit la structure de navigation:
# 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)Chaque puce dans SUMMARY.md devient une page dans votre barre latérale GitBook. Après avoir converti vos documents Word, organisez-les dans cette structure.
Le sujet principal dans GitBook
GitBook (versions anciennes) n'utilise pas le frontmatter YAML les titres des pages proviennent du premier titre H1. GitBooks version plus récente (GitBook.com) accepte un peu de matière première, mais l'approche sûre est d'utiliser la première # Heading comme titre de page:
# Authentication Guide
This section describes how to authenticate with the API.
## Overview
...Structure des rubriques
GitBook génère un tableau de contenu au niveau de la page à partir des en-têtes H2 et H3. Gardez votre hiérarchie propre:
- H1 Titre de page (un par fichier)
- H2 Les sections principales (apparaissent dans la page TOC)
- H3 sous-sections
Voir aussi: Markdown Guide des rubriques pour les meilleures pratiques.
Tableaux en GitBook
GitBook rend les tables GFM avec le style. Convertissez correctement les tables de votre document Word via WordToMD:
| Endpoint | Method | Description |
|---|---|---|
| `/auth/login` | POST | Authenticate user |
| `/auth/logout` | POST | End session |
| `/users/{id}` | GET | Get user profile |Pour les scénarios de table complexes, voir Markdown Tableaux: un guide complet.
Blocs de code
GitBook rend des blocs de code clôturés avec mise en évidence de la syntaxe. Après conversion avec WordToMD, formater correctement les échantillons de code:
```bash
npm install -g gitbook-cli
gitbook init my-docs
```GitBook possède également un type de bloc Hint spécial pour les appels:
{% hint style="info" %}
This is an information callout.
{% endhint %}
{% hint style="warning" %}
This is a warning callout.
{% endhint %}Si votre document Word a mis en surbrillance des cases d'appel, convertissez-les en blocs d'indices GitBook après la conversion initiale Markdown.
GitHub Synchroniser le flux de travail
GitBook prend en charge la synchronisation avec un référentiel GitHub:
- Créez un GitHub repo et ajoutez vos fichiers .md convertis
- Connectez GitBook au référentiel dans les paramètres GitBooks
- GitBook crée et publie automatiquement à partir des fichiers Markdown
- Les modifications de GitBook sont synchronisées avec GitHub, et vice versa
Cela vous donne un contrôle de version pour vos documents et permet à votre équipe de collaborer via GitHub PRs ou directement dans l'éditeur GitBook.
Pour les spécificités GitHub Markdown, voir Pour les personnes âgées, les conditions suivantes sont réunies:.
Des images
Exporter des images à partir de vos documents Word (Enregistrer en tant que page Web enregistre les images dans un dossier). Dans GitBook avec GitHub synchronisation, engager les images à un assets/ or images/ répertoire et les référencer:
Dans l'éditeur web GitBook, vous pouvez télécharger des images directement lors de l'édition de pages.
Migration d'un ensemble de documents complets
Pour une migration de documentation de grande taille de Word à GitBook:
- Vérifier les documents Word identifier les pages, les sections et la hiérarchie
- Planifier la structure SUMMARY.md avant conversion
- Convertir des fichiers with WordToMD (ou conversion par lots pour les grands volumes)
- Créer un résumé correspondant à votre structure prévue
- Examiner chaque page pour la hiérarchie des en-têtes, le formatage des tableaux et les blocs de code
- Publié par GitBooks import ou GitHub synchronisation
FAQ
Quelle saveur Markdown utilise GitBook ? GitBook utilise le standard Markdown (CommonMark) plus ses propres extensions (blocs d'indications, onglets, blocs d'intégration). La sortie Markdown de WordToMD est compatible.
Puis-je importer un .docx directement dans GitBook ? GitBook.com's import fonctionnalité accepte Word documents, mais la sortie est souvent de qualité inférieure à passer par Markdown. L'approche en deux étapes (Word → Markdown → GitBook) donne de meilleurs résultats pour les documents complexes.
Comment gérer les liens entre documents ?
Dans GitBook avec GitHub synchronisation, utilisez des liens relatifs Markdown: [See Authentication](../api/authentication.md). GitBook resolves these to proper page links.
Ma documentation contient plus de 50 fichiers Word. Y a-t-il un flux de travail plus rapide ? Voir aussi: Conversion par lots de Word à Markdown pour automatiser l'étape de conversion, puis écrire un script pour générer SUMMARY.md à partir de la structure de fichier.
Conclusion de l'enquête
La conversion Pour les personnes âgées, les conditions suivantes sont réunies: est un flux de travail propre: WordToMD gère la conversion du document, et GitBooks GitHub synchronisation ou importation directe gère la publication. Utilisez des styles d'en-tête standard dans Word, gardez vos tableaux simples, et vous aurez un site de documentation professionnelle fonctionnant rapidement.