Configuration du contenu

Configurez Git Sync avec des fonctionnalités supplémentaires

Si vous souhaitez aller plus loin dans la configuration de Git Sync, vous pouvez ajouter un .gitbook.yaml fichier à la racine du contenu synchronisé pour cet espace afin d’indiquer à GitBook comment analyser votre dépôt Git. Dans un monorepo, ce fichier se trouve dans le répertoire du projet.

.gitbook.yaml

racine : ./

structure :
  readme : README.md
  summary : SUMMARY.md

redirections :
  previous/page : new-folder/page.md

Racine

Le chemin à parcourir pour trouver votre documentation pointe par défaut vers le répertoire racine du dépôt. Voici comment indiquer à GitBook de regarder dans un ./docs dossier :

.gitbook.yaml

racine : ./docs/

Toutes les autres options qui spécifient des chemins seront relatives à ce dossier racine. Donc si vous définissez la racine comme ./docs/ puis structure.summary comme ./product/SUMMARY.md, GitBook cherchera en fait un fichier dans ./docs/product/SUMMARY.md.

Dans un monorepo, racine est résolue par rapport au répertoire du projet de l’espace synchronisé, et non à la racine du dépôt. La configuration basée sur les chemins ne s’applique qu’à l’intérieur du périmètre synchronisé de cet espace. Elle ne rend pas automatiquement les répertoires frères ou les dossiers à l’échelle du dépôt disponibles aux autres espaces. Pour les configurations de dépôt multi-espaces, voir Monorepos.

Structure

La structure accepte deux propriétés :

• readme: La première page de votre documentation. Sa valeur par défaut est ./README.md

• summary: La table des matières de votre documentation. Sa valeur par défaut est ./SUMMARY.md

La valeur de ces propriétés est un chemin vers les fichiers correspondants. Le chemin est relatif à l’option « root ». Par exemple, voici comment indiquer à GitBook de regarder dans un ./product dossier pour la première page et le résumé :

.gitbook.yaml

structure :
  readme : ./product/README.md
  summary : ./product/SUMMARY.md

Lorsque Git Sync est activé, n’oubliez pas de créer ou de modifier les fichiers readme via l’interface utilisateur de GitBook. Le fichier readme doit être géré exclusivement dans votre dépôt GitHub/GitLab afin d’éviter les conflits et les problèmes de duplication.

Résumé

Le summary fichier est un fichier Markdown (.md) qui doit avoir la structure suivante :

./SUMMARY.md

# Résumé

## Utilisez des titres pour créer des groupes de pages comme celui-ci

* [Titre de la première page](page1/README.md)
    * [Une page enfant](page1/page1-1.md)
    * [Une autre page enfant](part1/page1-2.md)

* [Titre de la deuxième page](page2/README.md)
    * [Une page enfant](page2/page2-1.md)
    * [Une autre page enfant](part2/page2-2.md)

## Un groupe de deuxième page

* [Une autre page](another-page.md)

Fournir un fichier de résumé personnalisé est facultatif. Par défaut, GitBook cherchera un fichier nommé SUMMARY.md dans votre racine dossier si cela est spécifié dans votre fichier de configuration, ou sinon à la racine du dépôt.

Si vous ne spécifiez pas de résumé et que GitBook ne trouve pas de SUMMARY.md fichier à la racine de votre documentation, GitBook déduira la table des matières à partir de la structure des dossiers et des fichiers Markdown ci-dessous.

Le fichier Markdown du résumé est un miroir de la table des matières de votre espace GitBook. Ainsi, même lorsqu’aucun fichier de résumé n’est fourni lors d’une importation initiale, GitBook en créera un et/ou le mettra à jour chaque fois que vous modifierez votre contenu à l’aide de l’éditeur GitBook.

Pour cette raison, il n’est pas possible de référencer deux SUMMARY.md fois le même fichier Markdown dans votre

fichier, car cela impliquerait qu’une seule page se trouve à deux URL différentes dans votre espace GitBook.

titres dans la table des matières (barre latérale) titre du lien de page dans votre SUMMARY.md fichier.

Si vous utilisez Git Sync, le titre du lien de page est défini sur le lien de page :

./SUMMARY.md

# Résumé

* [Titre principal de la page](page.md "Titre du lien de page")

Le texte entre guillemets ("Titre du lien de page") sera utilisé :

• Dans la table des matières (barre latérale)

• Dans les boutons de pagination en bas de chaque page

• Dans tous les liens relatifs que vous ajoutez à cette page

Les titres de lien de page sont facultatifs — si vous n’en ajoutez pas manuellement, GitBook utilisera par défaut partout le titre standard de la page.