Configuración global

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.

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.

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

Configuración

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.

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

{
  "groups": [
    {
      "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.

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.

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

Migración desde mint.json

Si tu proyecto utiliza el archivo mint.json obsoleto, usa la CLI para migrar a docs.json.

npm i -g mint

mint update

mint dev