Implementaciones multi-repositorio

Combina varios repositorios de Git en un único sitio de Mintlify, con una ruta de URL dedicada al contenido y la navegación de cada repositorio.

Las implementaciones multi-repositorio están disponibles en los planes Enterprise.

Usa una implementación multi-repositorio cuando un sitio necesite contenido de más de un repositorio de Git. Cuando configuras varios repositorios como fuentes del mismo proyecto de Mintlify, el contenido de cada repositorio tiene su propia ruta de URL.

Por ejemplo, puedes combinar repositorios separados de documentación de producto, referencia de API y guías de SDK en un único sitio:

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

​

Cómo funcionan las implementaciones multi-repositorio

Cada repositorio en una implementación multi-repositorio tiene su propio:

• Conexión con el proveedor de Git
• Rama
• Directorio de contenido opcional
• Ruta de URL
• docs.json

Durante la implementación, Mintlify lee cada repositorio y combina las fuentes configuradas en un único sitio. Cada fuente aparece bajo su ruta de URL configurada.

Un repositorio actúa como la fuente base de la implementación. Su docs.json es el docs.json raíz y controla la configuración a nivel de sitio, incluyendo el tema, los colores, el logotipo, el nombre del sitio, la navegación de nivel superior, las integraciones, el SEO y otros campos de nivel superior. Las demás fuentes aportan únicamente su propia navegación y contenido bajo su ruta de URL configurada. El primer repositorio que configures es la fuente base de manera predeterminada, y puedes cambiar qué fuente es la base en cualquier momento.

Las implementaciones multi-repositorio son distintas a una configuración de monorepo. Usa una configuración de monorepo cuando almacenes todo el contenido en un subdirectorio junto con el código fuente en un único repositorio. Usa implementaciones multi-repositorio cuando almacenes el contenido en repositorios distintos.

​

Requisitos

• Un plan Enterprise
• Acceso de administrador a tu proyecto de Mintlify
• Un archivo docs.json en cada repositorio de origen
• Todas las fuentes de repositorio deben usar el mismo proveedor de Git (todas GitHub o todas GitLab). Añadir una fuente de un proveedor distinto elimina todas las fuentes existentes del otro tipo

Las rutas de URL deben ser únicas y no pueden superponerse. Por ejemplo, no configures una fuente en /docs y otra fuente en /docs/api.

​

Configurar varios repositorios

1. Abrir la configuración de Git

   Ve a la configuración de Git en tu panel.

   
2. Añadir otro repositorio

   Haz clic en Add repository.

3. Configurar la fuente del repositorio

   Selecciona el repositorio, la rama y los campos específicos del proveedor de Git que se requieran (GitHub o GitLab).

   

   Para fuentes de GitHub, la aplicación de GitHub de Mintlify debe tener acceso al repositorio. Para fuentes de GitLab, proporciona el ID del proyecto y un token de despliegue con el alcance read_repository.

   Si el docs.json del repositorio se encuentra en un subdirectorio en lugar de en la raíz, habilita docs.json is in a subdirectory e introduce la ruta a ese directorio.

4. Establecer la ruta de URL

   Introduce una URL path para la fuente del repositorio.

   La ruta de URL determina dónde aparece el contenido de ese repositorio en tu sitio de documentación. Por ejemplo, una ruta de URL api sirve el contenido bajo docs.example.com/api.

   Puedes introducir la ruta con o sin barras iniciales. Mintlify normaliza el valor al guardar.

5. Guardar los cambios

   Haz clic en Save changes. Mintlify guarda la configuración y pone en cola un despliegue del sitio combinado.

​

Cambiar la fuente base

La fuente base proporciona la configuración a nivel de sitio para tu implementación multi-repositorio. Cambia la fuente base cuando quieras que el docs.json de un repositorio distinto controle ajustes como el tema, los colores, el nombre del sitio y la navegación de nivel superior.

1. Abrir la configuración de Git

   Ve a la configuración de Git en tu panel.

   La fuente base actual muestra una insignia Base junto al nombre del repositorio.

2. Establecer una nueva fuente base

   En el repositorio que quieras usar como base, selecciona Set as base.

   Mintlify actualiza la fuente base de inmediato y pone en cola una implementación que usa el docs.json del nuevo repositorio base para la configuración a nivel de sitio.

Cambiar la fuente base reemplaza la configuración a nivel de sitio (como el tema, los colores, el logotipo, el nombre del sitio y la navegación de nivel superior) por los valores del docs.json del nuevo repositorio base. Las rutas de URL y el contenido de las demás fuentes no se ven afectados.

​

Ejemplo de organización de repositorios

En este ejemplo, cada fuente tiene su propio repositorio y su propio 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/

Configura cada repositorio con una ruta de URL:

Repositorio	Ruta de URL	Ruta publicada
acme/product-docs	product	/product
acme/api-docs	api	/api
acme/sdk-docs	sdks	/sdks

​

Comportamiento de la navegación

Mintlify combina la navegación de cada repositorio en una única navegación del sitio. Cada fuente de repositorio se convierte en una sección de producto de nivel superior bajo la ruta de URL configurada.

El nombre de cada sección de producto proviene del campo name en el docs.json del repositorio correspondiente. Por ejemplo, si el docs.json de un repositorio establece "name": "API Reference", su sección de producto aparece como “API Reference” en la navegación combinada.

Mantén la navegación de cada fuente acotada a ese repositorio. Por ejemplo, las páginas en el repositorio de API deben referenciar solo archivos que estén en el repositorio de API, y las páginas en el repositorio de SDK deben referenciar solo archivos que estén en el repositorio de SDK.

Las configuraciones anidadas de navigation.products no son compatibles dentro de los repositorios de origen individuales.

​

Enlazar entre fuentes

Los enlaces de Markdown relativos no se pueden resolver entre repositorios porque cada fuente solo ve sus propios archivos en el momento de la compilación. Para enlazar desde una fuente a una página de otra fuente, usa una ruta URL relativa a la raíz que incluya la ruta URL de la fuente de destino:

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

En este ejemplo, /api es la ruta URL configurada para la fuente del repositorio de API. El enlace se resuelve a nivel del sitio publicado como docs.example.com/api/reference/authentication.

No uses URLs completas con https:// para enlaces internos entre fuentes: las rutas relativas a la raíz mantienen el correcto funcionamiento de las previsualizaciones y los dominios personalizados.

​

Referenciar la navegación desde otra fuente

Usa sourceRef para ubicar la navegación de otro repositorio en una posición específica dentro del docs.json de la fuente base. Si no usas sourceRef, Mintlify agrega cada repositorio como una sección de producto de nivel superior independiente.

​

Requisitos

• El repositorio referenciado debe estar configurado como una fuente en la misma implementación multi-repositorio.
• Los valores de sourceRef deben usar el formato owner/repo. Las rutas de montaje y los nombres de repositorio por sí solos no son compatibles.
• La fuente referenciada debe definir un patrón de navegación similar al de la fuente principal. Por ejemplo, un sourceRef dentro de anchors requiere que la fuente referenciada defina navigation.anchors.
• Las entradas de sourceRef no pueden formar un ciclo. Una fuente no puede referenciarse a sí misma, y dos fuentes no pueden referenciarse entre sí.
• sourceRef debe aparecer dentro de un arreglo de navegación. No es válido en el nivel superior de navigation.

​

Uso

Agrega una entrada sourceRef a un arreglo de navegación en el docs.json de la fuente base. El valor debe ser el identificador owner/repo del repositorio.

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

sourceRef es compatible dentro de anchors, tabs, groups, pages, products y los arreglos bajo navigation.global.

Por ejemplo, para combinar los anchors de varios repositorios en una sola navegación de anchors:

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

Si acme/api-docs define su propio navigation.anchors, Mintlify reemplaza la entrada sourceRef con esos anchors y les antepone la ruta de URL de la fuente referenciada.

​

Eliminar una fuente de repositorio

Puedes eliminar una fuente de repositorio desde la página de configuración de Git en tu panel. Cuando solo queda una fuente de repositorio, Mintlify elimina la ruta de URL de la fuente y trata el repositorio restante como la fuente raíz de la implementación.