Configuration du contenu

Configurer la synchronisation Git avec des fonctionnalités supplémentaires

Si vous souhaitez configurer davantage la synchronisation Git, vous pouvez ajouter un fichier .gitbook.yaml à la racine de votre dépôt pour indiquer à GitBook comment analyser votre dépôt Git.

.gitbook.yaml

root: ./

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

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

Racine

Le chemin de recherche de votre documentation est par défaut le répertoire racine du dépôt. Voici comment indiquer à GitBook de chercher dans un dossier ./docs :

.gitbook.yaml

root: ./docs/

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

​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 chercher dans un dossier ./product pour la première page et le sommaire :

.gitbook.yaml

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

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

Résumé‌

Le fichier summary 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 summary personnalisé est optionnel. Par défaut, GitBook recherchera un fichier nommé SUMMARY.md dans votre dossier root s’il est spécifié dans votre fichier de configuration, ou à la racine du dépôt sinon.

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

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

Pour cette raison, il n’est pas possible de référencer deux fois le même fichier Markdown dans votre fichier SUMMARY.md, car cela impliquerait qu’une seule page existe à deux URL différentes dans votre espace GitBook.

​Redirections

Les redirections vous permettent de définir des redirections dans votre fichier de configuration .gitbook.yaml. Le chemin est relatif à l’option « root ». Par exemple, voici comment indiquer à GitBook de rediriger les utilisateurs accédant à une ancienne url /help vers une nouvelle url /support

.gitbook.yaml

root: ./

redirects :
  help: support.md

Les redirections que vous définissez dans le fichier de configuration d’un espace sont limitées à l’espace correspondant. Nous recommandons de créer des redirections de site dans la plupart des cas car elles s’appliquent à l’ensemble du site, à travers les espaces.

Avec Git, lorsqu’un fichier est déplacé plusieurs fois, le fichier est supprimé et un nouveau est créé. Cela rend impossible pour GitBook de savoir, par exemple, qu’un dossier a été renommé. Assurez-vous de vérifier et d’ajouter des redirections si nécessaire.