Monorepos

GitBook prend en charge les monorepos. Un monorepo est un dépôt qui contient plus d’un projet logique (par exemple un client iOS et une application web).

GitBook peut synchroniser plusieurs répertoires du même dépôt avec plusieurs espaces. Lorsque vous activez Git Sync sur un espace, vous pouvez configurer un « Project directory ». Il sera utilisé pour rechercher le .gitbook.yaml fichier du répertoire à synchroniser avec cet espace.

Exemple d’une structure de dépôt :

/
  package.json
  packages/
     styleguide/
        .gitbook.yaml
        README.md
        SUMMARY.md
     app/
        README.md
        SUMMARY.md
     api/
        .gitbook.yaml
        README.md
        SUMMARY.md

Dans cet exemple, trois espaces peuvent être créés dans GitBook et configurés avec différents répertoires de projet :

• packages/styleguide

• packages/app

• packages/api

L’option « Project directory » au niveau de Git Sync diffère de l’ racine option dans le .gitbook.yaml fichier de configuration. La première est utilisée pour rechercher .gitbook.yaml elle-même, puis les deux sont combinées pour rechercher le reste des fichiers dans le répertoire. Si aucun .gitbook.yaml n’existe dans le « Project directory », la synchronisation utilisera la configuration par défaut limitée à ce répertoire.

Comment fonctionnent les répertoires et les ressources dans les dépôts multi-espaces

Chaque espace synchronisé a son propre répertoire de projet. GitBook lit le fichier de cet espace .gitbook.yaml depuis le répertoire de projet configuré. Il résout ensuite racine, README.md, SUMMARY.md, les fichiers Markdown et les chemins des ressources à partir du périmètre synchronisé de cet espace.

Dans un monorepo, chaque espace synchronisé est limité à son propre répertoire et à ses propres fichiers. Un espace différent synchronisé depuis un autre répertoire n’hérite pas automatiquement des fichiers d’ailleurs dans le dépôt et ne les réutilise pas.

Les ressources suivent la même règle. Un dossier .gitbook/assets au niveau du dépôt n’est pas partagé automatiquement entre les espaces si ces espaces utilisent des répertoires de projet différents.

Si plusieurs espaces ont besoin des mêmes fichiers, utilisez l’un de ces modèles :

• Placez les ressources à l’intérieur du répertoire de chaque espace.

• Réorganisez le dépôt de sorte que le périmètre synchronisé de chaque espace contienne les ressources qu’il référence.

Lorsque vous configurez un nouvel espace dans un monorepo, créez d’abord dans le dépôt la structure de répertoires souhaitée. GitBook n’infère pas pour vous une disposition multi-espace partagée et ne crée pas de zone de ressources partagée.

Pour plus de détails sur la façon dont racine est résolu à l’intérieur du périmètre synchronisé d’un espace, voir Configuration du contenu.

Voici un exemple concret :

/
  packages/
    docs-en/
      .gitbook.yaml
      README.md
      SUMMARY.md
      .gitbook/
        assets/
          logo.png
    docs-fr/
      .gitbook.yaml
      README.md
      SUMMARY.md
      .gitbook/
        assets/
          logo.png

Dans ce dépôt, packages/docs-en et packages/docs-fr sont deux espaces synchronisés distincts. Un fichier référencé depuis packages/docs-en/.gitbook/assets/logo.png n’est pas automatiquement disponible pour l’espace synchronisé depuis packages/docs-fr.

Mettre à jour le répertoire de projet

Dans la plupart des cas, nous recommandons l’étape suivante pour mettre à jour le répertoire de projet :

1. Désactiver la synchronisation Git existante

2. Déplacer les fichiers du dépôt Git vers le répertoire de projet

3. Reconfigurer la synchronisation Git avec le nouveau répertoire de projet

Dans certains cas, vous avez peut-être commencé avec un dépôt classique synchronisé avec un seul espace, puis décidé de le faire évoluer vers un monorepo avec plusieurs espaces le synchronisant ; ou vous devez peut-être renommer le répertoire de projet.

Modifier le répertoire de projet d’une synchronisation Git existante peut avoir un impact inattendu sur le contenu ; le changement ne sera propagé qu’au cours de la prochaine synchronisation (modification effectuée dans GitBook ou nouveau commit dans le dépôt Git).

GitBook s’attend à ce que tous les fichiers liés à GitBook pour cet espace existent à l’intérieur du répertoire de projet configuré. Cela inclut les fichiers Markdown, README.md, SUMMARY.md, ainsi que toutes les ressources utilisées par cet espace.

Si la prochaine opération est une importation depuis le dépôt Git:

GitBook s’attendra à trouver les pages et les fichiers dans le répertoire de projet. Si les fichiers n’ont pas déjà été déplacés dans le répertoire de projet du dépôt, le résultat de la synchronisation sera un espace vide, sans contenu.

Nous recommandons que la prochaine opération soit un commit déplaçant tous les fichiers liés à GitBook (fichiers Markdown, README/SUMMARY et ressources) dans le dépôt vers leur nouvel emplacement correct, dans le répertoire de projet. Si des ressources restent en dehors du nouveau répertoire de projet, ne vous attendez pas à ce qu’elles soient résolues pour cet espace.

Si la prochaine opération est une exportation de GitBook vers le dépôt Git:

GitBook générera ou mettra à jour de nouveaux fichiers dans le nouveau répertoire de projet. Les fichiers synchronisés avec GitBook seront déplacés vers le nouveau répertoire de projet (du mieux possible) ; cela peut entraîner des effets secondaires si d’autres parties de votre système dépendent de ces fichiers.