Déploiements multi-référentiels

Combinez des fichiers issus de plusieurs référentiels Git en un seul site Mintlify, avec un chemin d’URL pour chaque référentiel source.

Les déploiements multi-référentiels sont disponibles avec les plans Enterprise.

Utilisez un déploiement multi-référentiels lorsqu’un même site doit regrouper du contenu provenant de plusieurs référentiels Git. Lorsque vous configurez plusieurs référentiels comme sources d’un même projet Mintlify, le contenu de chaque référentiel dispose de son propre chemin d’URL.

Par exemple, vous pouvez combiner des référentiels distincts pour la documentation produit, la référence d’API et les guides SDK au sein d’un même site :

docs.example.com/product
docs.example.com/api
docs.example.com/sdks

​

Fonctionnement des déploiements multi-référentiels

Chaque référentiel d’un déploiement multi-référentiels possède :

• Sa propre connexion à un fournisseur Git
• Sa propre branche
• Un répertoire de contenu facultatif
• Son propre chemin d’URL
• Son propre docs.json

Lors du déploiement, Mintlify lit chaque référentiel et combine les sources configurées en un seul site. Chaque source apparaît sous son chemin d’URL configuré.

Un référentiel sert de source de base pour le déploiement. Son docs.json est le docs.json racine et contrôle la configuration au niveau du site, y compris le thème, les couleurs, le logo, le nom du site, la navigation de premier niveau, les intégrations, le SEO et les autres champs de premier niveau. Chaque autre source ne fournit que sa propre navigation et son propre contenu sous son chemin d’URL configuré. Le premier référentiel que vous configurez est la source de base par défaut, et vous pouvez changer la source de base à tout moment.

Les déploiements multi-référentiels sont différents d’une configuration monorepo. Utilisez une configuration monorepo lorsque vous stockez tout le contenu dans un sous-répertoire à côté du code source d’un même référentiel. Utilisez les déploiements multi-référentiels lorsque vous stockez le contenu dans des référentiels distincts.

​

Prérequis

• Un plan Enterprise
• Un accès administrateur à votre projet Mintlify
• Un fichier docs.json dans chaque référentiel source
• Toutes les sources doivent utiliser le même fournisseur Git (tout GitHub ou tout GitLab). L’ajout d’une source d’un autre fournisseur supprime toutes les sources existantes de l’autre type

Les chemins d’URL doivent être uniques et ne peuvent pas se chevaucher. Par exemple, ne configurez pas une source sur /docs et une autre sur /docs/api.

​

Configurer plusieurs référentiels

1. Ouvrir les paramètres Git

   Accédez aux paramètres Git dans votre tableau de bord.

   
2. Ajouter un autre référentiel

   Cliquez sur Add repository.

3. Configurer la source du référentiel

   Sélectionnez le référentiel, la branche et tous les champs requis spécifiques au fournisseur Git (GitHub ou GitLab).

   

   Pour les sources GitHub, l’application GitHub de Mintlify doit avoir accès au référentiel. Pour les sources GitLab, fournissez l’ID du projet et un jeton de déploiement avec la portée read_repository.

   Si le docs.json du référentiel se trouve dans un sous-répertoire plutôt qu’à la racine, activez docs.json is in a subdirectory et saisissez le chemin vers ce répertoire.

4. Définir le chemin d’URL

   Saisissez un URL path pour la source du référentiel.

   Le chemin d’URL détermine l’emplacement où le contenu de ce référentiel apparaît sur votre site de documentation. Par exemple, un chemin d’URL api diffuse le contenu sous docs.example.com/api.

   Vous pouvez saisir le chemin avec ou sans barre oblique de tête. Mintlify normalise la valeur lors de l’enregistrement.

5. Enregistrer les modifications

   Cliquez sur Save changes. Mintlify enregistre la configuration et met en file d’attente un déploiement du site combiné.

​

Changer la source de base

La source de base fournit la configuration au niveau du site pour votre déploiement multi-référentiels. Changez la source de base lorsque vous souhaitez que le docs.json d’un autre référentiel contrôle les paramètres tels que le thème, les couleurs, le nom du site et la navigation de premier niveau.

1. Ouvrir les paramètres Git

   Accédez aux paramètres Git dans votre tableau de bord.

   La source de base actuelle affiche un badge Base à côté du nom du référentiel.

2. Définir une nouvelle source de base

   Sur le référentiel que vous souhaitez utiliser comme base, sélectionnez Set as base.

   Mintlify met immédiatement à jour la source de base et met en file d’attente un déploiement qui utilise le docs.json du nouveau référentiel de base pour la configuration au niveau du site.

Changer la source de base remplace les paramètres au niveau du site (tels que le thème, les couleurs, le logo, le nom du site et la navigation de premier niveau) par les valeurs du docs.json du nouveau référentiel de base. Les chemins d’URL et le contenu des autres sources ne sont pas affectés.

​

Exemple d’organisation des référentiels

Dans cet exemple, chaque source dispose de son propre référentiel et de son propre docs.json.

acme/product-docs
├── docs.json
├── overview.mdx
└── guides/

acme/api-docs
├── docs.json
├── introduction.mdx
└── reference/

acme/sdk-docs
├── docs.json
├── quickstart.mdx
└── javascript/

Configurez chaque référentiel avec un chemin d’URL :

Référentiel	Chemin d’URL	Chemin publié
acme/product-docs	product	/product
acme/api-docs	api	/api
acme/sdk-docs	sdks	/sdks

​

Comportement de la navigation

Mintlify combine la navigation de chaque référentiel en une seule navigation de site. Chaque source de référentiel devient une section produit de premier niveau sous le chemin d’URL configuré.

Le nom de chaque section produit provient du champ name du docs.json du référentiel correspondant. Par exemple, si le docs.json d’un référentiel définit "name": "API Reference", sa section produit apparaît comme « API Reference » dans la navigation combinée.

Conservez une navigation cantonnée à chaque source. Par exemple, les pages du référentiel API ne doivent référencer que des fichiers qui se trouvent dans le référentiel API, et les pages du référentiel SDK ne doivent référencer que des fichiers qui se trouvent dans le référentiel SDK.

Les configurations imbriquées navigation.products ne sont pas prises en charge à l’intérieur des référentiels sources individuels.

​

Créer des liens entre sources

Les liens Markdown relatifs ne peuvent pas être résolus entre référentiels, car chaque source ne voit que ses propres fichiers au moment de la compilation. Pour lier une page d’une source à une page d’une autre source, utilisez un chemin d’URL relatif à la racine qui inclut le chemin d’URL de la source de destination :

See the [API reference](/api/reference/authentication) for details.

Dans cet exemple, /api est le chemin d’URL configuré pour la source du référentiel API. Le lien est résolu au niveau du site publié en docs.example.com/api/reference/authentication.

N’utilisez pas d’URL complètes https:// pour les liens internes entre sources — les chemins relatifs à la racine permettent aux previews et aux domaines personnalisés de continuer à fonctionner correctement.

​

Référencer la navigation d’une autre source

Utilisez sourceRef pour placer la navigation d’un autre référentiel à un emplacement précis dans le docs.json de la source de base. Si vous n’utilisez pas sourceRef, Mintlify ajoute chaque référentiel comme une section produit distincte de niveau supérieur.

​

Prérequis

• Le référentiel référencé doit être configuré comme source dans le même déploiement multi-référentiels.
• Les valeurs de sourceRef doivent utiliser le format owner/repo. Les chemins de montage et les noms de référentiel seuls ne sont pas pris en charge.
• La source référencée doit définir un schéma de navigation similaire à celui de la source principale. Par exemple, un sourceRef à l’intérieur de anchors exige que la source référencée définisse navigation.anchors.
• Les entrées sourceRef ne peuvent pas former de cycle. Une source ne peut pas se référencer elle-même, et deux sources ne peuvent pas se référencer mutuellement.
• sourceRef doit apparaître à l’intérieur d’un tableau de navigation. Il n’est pas valide au niveau supérieur de navigation.

​

Utilisation

Ajoutez une entrée sourceRef à un tableau de navigation dans le docs.json de la source de base. La valeur doit être l’identifiant owner/repo du référentiel.

{ "sourceRef": "acme/api-docs" }

sourceRef est pris en charge dans anchors, tabs, groups, pages, products et les tableaux sous navigation.global.

Par exemple, pour combiner les anchors de plusieurs référentiels dans une seule navigation d’anchors :

{
  "navigation": {
    "anchors": [
      {
        "anchor": "Guides",
        "pages": ["quickstart"]
      },
      {
        "sourceRef": "acme/api-docs"
      }
    ]
  }
}

Si acme/api-docs définit son propre navigation.anchors, Mintlify remplace l’entrée sourceRef par ces anchors et préfixe leurs chemins avec le chemin d’URL de la source référencée.

​

Supprimer une source de référentiel

Vous pouvez supprimer une source de référentiel depuis la page des paramètres Git de votre tableau de bord. Lorsqu’il ne reste plus qu’une seule source de référentiel, Mintlify supprime le chemin d’URL de la source et traite le référentiel restant comme la source racine du déploiement.