Configuración global

Configura tu sitio de documentación Mintlify con docs.json, el archivo de configuración obligatorio que controla la navegación, la apariencia, las integraciones y más.

El archivo docs.json es el archivo de configuración central de tu sitio de documentación Mintlify. Controla la configuración global de tu sitio, incluyendo la identidad visual, la estructura de navegación, las integraciones, la configuración de la API y más. Piensa en él como el plano de tu sitio.

​

Campos obligatorios

Debes definir cuatro campos para construir un sitio funcional.

Campo	Descripción
name	El nombre de tu proyecto u organización
theme	El tema de diseño de tu sitio
colors.primary	El color principal de la marca como código hexadecimal
navigation	La estructura de tu contenido

Todos los demás campos son opcionales. Agrégalos a medida que personalices y refines tu sitio.

​

Configuración mínima

Para la mejor experiencia de edición, incluye la referencia $schema en la parte superior de tu docs.json. Esto habilita el autocompletado, la validación y la documentación en línea en la mayoría de los editores.

docs.json

{
  "$schema": "https://mintlify.com/docs.json",
  "theme": "mint",
  "name": "Your project name",
  "colors": {
    "primary": "#ff0000"
  },
  "navigation": [
    {
      "group": "Home",
      "pages": ["index"]
    }
  ]
}

​

Configuración

Apariencia y marca

Personaliza la apariencia visual de tu sitio, incluyendo el tema, los colores, el logo, el favicon, las fuentes y el fondo.

Estructura del sitio

Diseña la arquitectura de información y la experiencia de usuario de tu sitio, incluyendo la barra de navegación, el pie de página, el banner, la navegación y las redirecciones.

Configuración de la API

Controla la visualización y el comportamiento de la documentación de la API, incluyendo las especificaciones OpenAPI y AsyncAPI, el área de pruebas de la API y los ejemplos de código.

Integraciones

Conecta tu sitio a servicios de terceros para analytics, chat y más.

SEO y búsqueda

Controla cómo los motores de búsqueda indexan tu sitio, incluyendo las meta tags, la búsqueda y las marcas de tiempo de las páginas.

Referencia del esquema

Referencia completa de todas las propiedades de docs.json.

​

Dividir la configuración con $ref

A medida que tu configuración crece, puedes dividir docs.json en archivos más pequeños usando referencias $ref. Cada referencia apunta a un archivo JSON separado que se resuelve en tiempo de compilación.

Agrega una propiedad $ref con una ruta de archivo relativa en cualquier lugar de tu docs.json. Mintlify reemplaza el objeto $ref con el contenido del archivo referenciado.

docs.json

{
  "$schema": "https://mintlify.com/docs.json",
  "theme": "mint",
  "name": "Acme Docs",
  "colors": {
    "primary": "#1a73e8"
  },
  "navigation": {
    "$ref": "./config/navigation.json"
  }
}

config/navigation.json

[
  {
    "group": "Get started",
    "pages": ["index", "quickstart"]
  },
  {
    "group": "Guides",
    "pages": ["guides/first-steps", "guides/advanced"]
  }
]

• Los archivos referenciados pueden contener sus propias referencias $ref. Las rutas anidadas se resuelven de forma relativa al archivo que las contiene, no de forma relativa a docs.json.
• Las referencias deben apuntar a archivos JSON válidos.
• Las rutas deben ser relativas y permanecer dentro de la raíz del proyecto. La navegación de rutas (por ejemplo, ../../outside) no está permitida.
• Las referencias circulares provocan un error de compilación.

​

Fusión de claves hermanas

Si un $ref resuelve a un objeto, Mintlify fusiona las claves hermanas del mismo bloque sobre el contenido referenciado, permitiendo que esas claves tengan prioridad sobre las claves coincidentes en la referencia. Si un $ref resuelve a un valor que no es un objeto, como un array, Mintlify ignora las claves hermanas.

docs.json

{
  "appearance": {
    "$ref": "./config/appearance.json",
    "strict": true
  }
}

​

Migración desde mint.json

Si tu proyecto utiliza el archivo mint.json obsoleto, sigue estos pasos para migrar a docs.json.

1. Instalar o actualizar el CLI

   Si no has instalado el CLI, instálalo ahora:

   npm

   npm i -g mint
   

   Si ya tienes el CLI instalado, asegúrate de que esté actualizado:

   mint update
   
2. Crear tu archivo docs.json

   En tu repositorio de documentación, ejecuta:

   mint upgrade
   

   Este comando crea un archivo docs.json a partir de tu mint.json existente. Revisa el archivo generado para asegurarte de que toda la configuración sea correcta.

3. Eliminar tu archivo mint.json

   Después de verificar que tu docs.json está configurado correctamente, puedes eliminar de forma segura tu antiguo archivo mint.json.