docs: document multi-source navigation merging

deploy/multiple-sources.mdx

@@ -0,0 +1,114 @@
+---
+title: "Multiple sources"
+description: "Pull documentation from multiple git repositories into a single Mintlify deployment, with each source mounted under its own path."
+keywords: ["multi-source", "multiple repos", "git sources", "mount path", "products"]
+---
+
+Connect more than one git repository to a single Mintlify deployment. Each repository, called a _source_, contributes its own `docs.json` and content, and Mintlify merges them into one site at build time. Use multi-source deployments when documentation for related products lives in separate repositories but should appear under a single domain and navigation tree.
+
+## How sources are merged
+
+When a deployment has more than one source, Mintlify fetches each source's `docs.json` during every build and merges them into a single `navigation.products` tree:
+
+* The **first source listed on the deployment** is the _primary source_. Its `docs.json` provides the top-level configuration for the merged site, including `name`, `theme`, `colors`, `logo`, `favicon`, `redirects`, and any other top-level fields.
+* **Additional sources** contribute only their `navigation`. Other top-level fields in those configs (for example, `redirects` or `theme`) are ignored, and a warning is logged at build time listing the ignored keys.
+* Each source's `navigation` becomes one entry in the merged `navigation.products` array. The product's display name is the source's label, or its `docs.json` `name` if no label is set.
+
+The merged result is equivalent to a single `docs.json` that uses [products](/organize/navigation#products) as its top-level navigation division.
+
+<Note>
+A source's `docs.json` cannot itself use `navigation.products`. Products only exist at the merged top level, so each source must use a non-product navigation (for example, `groups`, `tabs`, `versions`, or `anchors`).
+</Note>
+
+## Mount paths
+
+Every source on a multi-source deployment must have a non-empty **mount path**. The mount path is the URL prefix that the source's content is served under, and it is prepended to every reference in that source's `docs.json` during the merge:
+
+* Page paths in `pages`, `root`, and `href` fields. For example, `quickstart` from a source mounted at `eng` resolves to `eng/quickstart`.
+* OpenAPI and AsyncAPI references in `openapi` and `asyncapi` fields, including `source` and `directory` properties.
+* `href` values in global navigation entries such as `anchors` and `tabs`.
+
+Absolute URLs (`https://…`) and in-page anchors (`#section`) are left unchanged. Mount paths cannot overlap between sources on the same deployment.
+
+The resulting URLs in your live site include the mount path. A page authored as `quickstart.mdx` in a source mounted at `eng` is served at `/eng/quickstart`.
+
+## Example
+
+A deployment with two sources — one mounted at `platform`, one mounted at `eng` — produces a merged config that looks like this:
+
+**Primary source `docs.json` (mounted at `platform`):**
+
+```json
+{
+  "$schema": "https://mintlify.com/docs.json",
+  "theme": "mint",
+  "name": "Acme Docs",
+  "colors": { "primary": "#0D9373" },
+  "favicon": "/favicon.svg",
+  "redirects": [{ "source": "/old", "destination": "/new" }],
+  "navigation": {
+    "groups": [
+      { "group": "Get started", "pages": ["index", "setup"] }
+    ]
+  }
+}
+```
+
+**Second source `docs.json` (mounted at `eng`):**
+
+```json
+{
+  "$schema": "https://mintlify.com/docs.json",
+  "name": "Engineering",
+  "navigation": {
+    "groups": [
+      { "group": "Guides", "pages": ["quickstart"] }
+    ]
+  }
+}
+```
+
+**Merged config Mintlify builds and serves:**
+
+```json
+{
+  "$schema": "https://mintlify.com/docs.json",
+  "theme": "mint",
+  "name": "Acme Docs",
+  "colors": { "primary": "#0D9373" },
+  "favicon": "/favicon.svg",
+  "redirects": [{ "source": "/old", "destination": "/new" }],
+  "navigation": {
+    "products": [
+      {
+        "product": "Platform",
+        "groups": [
+          { "group": "Get started", "pages": ["platform/index", "platform/setup"] }
+        ]
+      },
+      {
+        "product": "Engineering",
+        "groups": [
+          { "group": "Guides", "pages": ["eng/quickstart"] }
+        ]
+      }
+    ]
+  }
+}
+```
+
+## Build failures
+
+The build fails and the deployment is not updated if:
+
+* Any source is missing a `docs.json`, or a source's `docs.json` is invalid.
+* Any source has an empty mount path.
+* Two sources have overlapping mount paths.
+* A source's `navigation` uses `products` at the top level.
+
+The build error names the source that caused the failure so you can fix it in that repository.
+
+## Related
+
+* [Monorepo setup](/deploy/monorepo) — pointing a single source at a subdirectory of a larger repository.
+* [Products](/organize/navigation#products) — the navigation division that multi-source deployments produce.

docs.json

@@ -206,6 +206,7 @@
                     ]
                   },
                   "deploy/monorepo",
+                  "deploy/multiple-sources",
                   "deploy/vercel-external-proxies",
                   "deploy/ci",
                   "deploy/github",

es.json

@@ -174,6 +174,7 @@
               ]
             },
             "es/deploy/monorepo",
+            "es/deploy/multiple-sources",
             "es/deploy/vercel-external-proxies",
             "es/deploy/ci",
             "es/deploy/github",

es/deploy/multiple-sources.mdx

@@ -0,0 +1,124 @@
+---
+title: "Múltiples fuentes"
+description: "Extrae documentación desde varios repositorios de git hacia un único despliegue de Mintlify, con cada fuente montada bajo su propia ruta."
+keywords: ["multi-source", "multiple repos", "git sources", "mount path", "products"]
+---
+
+Conecta más de un repositorio de git a un único despliegue de Mintlify. Cada repositorio, llamado _fuente_, aporta su propio `docs.json` y su contenido, y Mintlify los combina en un solo sitio durante la compilación. Usa despliegues de múltiples fuentes cuando la documentación de productos relacionados vive en repositorios separados pero debe aparecer bajo un único dominio y árbol de navegación.
+
+<div id="how-sources-are-merged">
+  ## Cómo se combinan las fuentes
+</div>
+
+Cuando un despliegue tiene más de una fuente, Mintlify obtiene el `docs.json` de cada fuente en cada compilación y los combina en un único árbol `navigation.products`:
+
+* La **primera fuente listada en el despliegue** es la _fuente principal_. Su `docs.json` proporciona la configuración de nivel superior para el sitio combinado, incluidos `name`, `theme`, `colors`, `logo`, `favicon`, `redirects` y cualquier otro campo de nivel superior.
+* Las **fuentes adicionales** solo aportan su `navigation`. Los demás campos de nivel superior en esas configuraciones (por ejemplo, `redirects` o `theme`) se ignoran, y se registra una advertencia durante la compilación que lista las claves ignoradas.
+* El `navigation` de cada fuente se convierte en una entrada del arreglo `navigation.products` combinado. El nombre visible del producto es la etiqueta de la fuente, o el `name` de su `docs.json` si no se ha establecido una etiqueta.
+
+El resultado combinado equivale a un único `docs.json` que usa [products](/es/organize/navigation#products) como su división de navegación de nivel superior.
+
+<Note>
+El `docs.json` de una fuente no puede usar `navigation.products`. Los products solo existen en el nivel superior combinado, por lo que cada fuente debe usar una navegación que no sea de products (por ejemplo, `groups`, `tabs`, `versions` o `anchors`).
+</Note>
+
+<div id="mount-paths">
+  ## Rutas de montaje
+</div>
+
+Cada fuente en un despliegue de múltiples fuentes debe tener una **ruta de montaje** no vacía. La ruta de montaje es el prefijo de URL bajo el cual se sirve el contenido de la fuente, y se antepone a cada referencia en el `docs.json` de esa fuente durante la combinación:
+
+* Rutas de página en los campos `pages`, `root` y `href`. Por ejemplo, `quickstart` de una fuente montada en `eng` se resuelve como `eng/quickstart`.
+* Referencias de OpenAPI y AsyncAPI en los campos `openapi` y `asyncapi`, incluidas las propiedades `source` y `directory`.
+* Valores `href` en entradas de navegación globales como `anchors` y `tabs`.
+
+Las URLs absolutas (`https://…`) y los anclas dentro de la página (`#section`) se dejan sin cambios. Las rutas de montaje no pueden superponerse entre fuentes del mismo despliegue.
+
+Las URLs resultantes en tu sitio publicado incluyen la ruta de montaje. Una página creada como `quickstart.mdx` en una fuente montada en `eng` se sirve en `/eng/quickstart`.
+
+<div id="example">
+  ## Ejemplo
+</div>
+
+Un despliegue con dos fuentes —una montada en `platform` y otra montada en `eng`— produce una configuración combinada que se ve así:
+
+**`docs.json` de la fuente principal (montada en `platform`):**
+
+```json
+{
+  "$schema": "https://mintlify.com/docs.json",
+  "theme": "mint",
+  "name": "Acme Docs",
+  "colors": { "primary": "#0D9373" },
+  "favicon": "/favicon.svg",
+  "redirects": [{ "source": "/old", "destination": "/new" }],
+  "navigation": {
+    "groups": [
+      { "group": "Get started", "pages": ["index", "setup"] }
+    ]
+  }
+}
+```
+
+**`docs.json` de la segunda fuente (montada en `eng`):**
+
+```json
+{
+  "$schema": "https://mintlify.com/docs.json",
+  "name": "Engineering",
+  "navigation": {
+    "groups": [
+      { "group": "Guides", "pages": ["quickstart"] }
+    ]
+  }
+}
+```
+
+**Configuración combinada que Mintlify compila y sirve:**
+
+```json
+{
+  "$schema": "https://mintlify.com/docs.json",
+  "theme": "mint",
+  "name": "Acme Docs",
+  "colors": { "primary": "#0D9373" },
+  "favicon": "/favicon.svg",
+  "redirects": [{ "source": "/old", "destination": "/new" }],
+  "navigation": {
+    "products": [
+      {
+        "product": "Platform",
+        "groups": [
+          { "group": "Get started", "pages": ["platform/index", "platform/setup"] }
+        ]
+      },
+      {
+        "product": "Engineering",
+        "groups": [
+          { "group": "Guides", "pages": ["eng/quickstart"] }
+        ]
+      }
+    ]
+  }
+}
+```
+
+<div id="build-failures">
+  ## Fallos de compilación
+</div>
+
+La compilación falla y el despliegue no se actualiza si:
+
+* A alguna fuente le falta un `docs.json`, o el `docs.json` de una fuente no es válido.
+* Alguna fuente tiene una ruta de montaje vacía.
+* Dos fuentes tienen rutas de montaje superpuestas.
+* El `navigation` de una fuente usa `products` en el nivel superior.
+
+El error de compilación indica el nombre de la fuente que causó el fallo para que puedas corregirlo en ese repositorio.
+
+<div id="related">
+  ## Relacionado
+</div>
+
+* [Configuración de monorepo](/es/deploy/monorepo) — apuntar una única fuente a un subdirectorio de un repositorio más grande.
+* [Products](/es/organize/navigation#products) — la división de navegación que producen los despliegues de múltiples fuentes.

fr.json

@@ -174,6 +174,7 @@
               ]
             },
             "fr/deploy/monorepo",
+            "fr/deploy/multiple-sources",
             "fr/deploy/vercel-external-proxies",
             "fr/deploy/ci",
             "fr/deploy/github",

fr/deploy/multiple-sources.mdx

@@ -0,0 +1,124 @@
+---
+title: "Sources multiples"
+description: "Récupérez la documentation depuis plusieurs référentiels git au sein d’un même déploiement Mintlify, chaque source étant montée sous son propre chemin."
+keywords: ["multi-source", "multiple repos", "git sources", "mount path", "products"]
+---
+
+Connectez plusieurs référentiels git à un seul déploiement Mintlify. Chaque référentiel, appelé _source_, fournit son propre `docs.json` ainsi que son contenu, et Mintlify les fusionne en un seul site au moment de la compilation. Utilisez les déploiements multi-sources lorsque la documentation de produits liés se trouve dans des référentiels distincts mais doit apparaître sous un même domaine et une même arborescence de navigation.
+
+<div id="how-sources-are-merged">
+  ## Comment les sources sont fusionnées
+</div>
+
+Lorsqu’un déploiement comporte plusieurs sources, Mintlify récupère le `docs.json` de chaque source à chaque compilation et les fusionne en une seule arborescence `navigation.products` :
+
+* La **première source listée sur le déploiement** est la _source principale_. Son `docs.json` fournit la configuration de niveau supérieur du site fusionné, notamment `name`, `theme`, `colors`, `logo`, `favicon`, `redirects` et tout autre champ de niveau supérieur.
+* Les **sources additionnelles** ne contribuent qu’à leur `navigation`. Les autres champs de niveau supérieur de ces configurations (par exemple, `redirects` ou `theme`) sont ignorés, et un avertissement est consigné lors de la compilation, listant les clés ignorées.
+* La `navigation` de chaque source devient une entrée dans le tableau `navigation.products` fusionné. Le nom d’affichage du produit est le libellé de la source, ou son `name` dans `docs.json` si aucun libellé n’est défini.
+
+Le résultat fusionné équivaut à un unique `docs.json` qui utilise les [products](/fr/organize/navigation#products) comme division de navigation de niveau supérieur.
+
+<Note>
+Le `docs.json` d’une source ne peut pas lui-même utiliser `navigation.products`. Les produits n’existent qu’au niveau supérieur fusionné, donc chaque source doit utiliser une navigation autre que par produit (par exemple, `groups`, `tabs`, `versions` ou `anchors`).
+</Note>
+
+<div id="mount-paths">
+  ## Chemins de montage
+</div>
+
+Chaque source d’un déploiement multi-sources doit avoir un **chemin de montage** non vide. Le chemin de montage est le préfixe d’URL sous lequel le contenu de la source est servi, et il est ajouté en préfixe à chaque référence dans le `docs.json` de cette source lors de la fusion :
+
+* Les chemins de page dans les champs `pages`, `root` et `href`. Par exemple, `quickstart` provenant d’une source montée sur `eng` est résolu en `eng/quickstart`.
+* Les références OpenAPI et AsyncAPI dans les champs `openapi` et `asyncapi`, y compris les propriétés `source` et `directory`.
+* Les valeurs `href` dans les entrées de navigation globale telles que `anchors` et `tabs`.
+
+Les URL absolues (`https://…`) et les ancres internes à la page (`#section`) sont laissées inchangées. Les chemins de montage ne peuvent pas se chevaucher entre les sources d’un même déploiement.
+
+Les URL résultantes sur votre site en ligne incluent le chemin de montage. Une page créée en tant que `quickstart.mdx` dans une source montée sur `eng` est servie à l’adresse `/eng/quickstart`.
+
+<div id="example">
+  ## Exemple
+</div>
+
+Un déploiement avec deux sources — une montée sur `platform`, une montée sur `eng` — produit une configuration fusionnée qui ressemble à ceci :
+
+**`docs.json` de la source principale (montée sur `platform`) :**
+
+```json
+{
+  "$schema": "https://mintlify.com/docs.json",
+  "theme": "mint",
+  "name": "Acme Docs",
+  "colors": { "primary": "#0D9373" },
+  "favicon": "/favicon.svg",
+  "redirects": [{ "source": "/old", "destination": "/new" }],
+  "navigation": {
+    "groups": [
+      { "group": "Get started", "pages": ["index", "setup"] }
+    ]
+  }
+}
+```
+
+**`docs.json` de la seconde source (montée sur `eng`) :**
+
+```json
+{
+  "$schema": "https://mintlify.com/docs.json",
+  "name": "Engineering",
+  "navigation": {
+    "groups": [
+      { "group": "Guides", "pages": ["quickstart"] }
+    ]
+  }
+}
+```
+
+**Configuration fusionnée que Mintlify compile et sert :**
+
+```json
+{
+  "$schema": "https://mintlify.com/docs.json",
+  "theme": "mint",
+  "name": "Acme Docs",
+  "colors": { "primary": "#0D9373" },
+  "favicon": "/favicon.svg",
+  "redirects": [{ "source": "/old", "destination": "/new" }],
+  "navigation": {
+    "products": [
+      {
+        "product": "Platform",
+        "groups": [
+          { "group": "Get started", "pages": ["platform/index", "platform/setup"] }
+        ]
+      },
+      {
+        "product": "Engineering",
+        "groups": [
+          { "group": "Guides", "pages": ["eng/quickstart"] }
+        ]
+      }
+    ]
+  }
+}
+```
+
+<div id="build-failures">
+  ## Échecs de compilation
+</div>
+
+La compilation échoue et le déploiement n’est pas mis à jour si :
+
+* Une source n’a pas de `docs.json`, ou le `docs.json` d’une source est invalide.
+* Une source a un chemin de montage vide.
+* Deux sources ont des chemins de montage qui se chevauchent.
+* La `navigation` d’une source utilise `products` au niveau supérieur.
+
+L’erreur de compilation indique le nom de la source à l’origine de l’échec afin que vous puissiez la corriger dans ce référentiel.
+
+<div id="related">
+  ## Ressources connexes
+</div>
+
+* [Configuration d’un monorepo](/fr/deploy/monorepo) — pointer une seule source vers un sous-répertoire d’un référentiel plus large.
+* [Products](/fr/organize/navigation#products) — la division de navigation que produisent les déploiements multi-sources.

zh.json

@@ -173,6 +173,7 @@
               ]
             },
             "zh/deploy/monorepo",
+            "zh/deploy/multiple-sources",
             "zh/deploy/vercel-external-proxies",
             "zh/deploy/ci",
             "zh/deploy/github",