Al crear portales de documentación orientados a desarrolladores modernos, un número creciente de equipos de ingeniería y redacción técnica opta por Mintlify. En lugar de mantener complejas capas de enrutamiento frontend o extensas hojas de estilo CSS personalizadas, Mintlify adopta la filosofía de "documentación como código" (Docs-as-Code). Toda la identidad visual y la arquitectura de la información se gestionan a través de un único archivo declarativo ubicado en la raíz del repositorio: docs.json (anteriormente mint.json). Los equipos pueden definir identidades de marca, barras laterales jerárquicas, secciones colapsables y grupos de pestañas de nivel superior directamente en un archivo JSON bajo control de versiones, junto a sus contenidos en formato MDX.
Esta guía examina en detalle cómo configurar el diseño de marca, estructurar barras laterales y organizar grupos de pestañas para portales de documentación técnicos de nivel empresarial.
1. Arquitectura de configuración central: El esquema de docs.json
Todo sitio de Mintlify está gobernado por el archivo docs.json en la raíz del proyecto. La especificación actual consolida temas de diseño, árboles de navegación, comportamiento de la consola de API e integraciones de análisis en una única estructura de datos.
Validación de esquemas y resolución de rutas
Para contar con autocompletado y validación de sintaxis en tiempo real en editores como VS Code, es altamente recomendable declarar el esquema oficial al inicio de docs.json:
{
"$schema": "https://mintlify.com/docs.json",
"name": "Centro de Desarrolladores Acme",
"theme": "maple"
}
Las convenciones de resolución de archivos más importantes son:
- Rutas sin extensión: Las rutas declaradas en las listas de navegación son relativas a la raíz del repositorio y omiten la extensión
.mdxo.md. Por ejemplo,"pages": ["getting-started/quickstart"]resuelve al archivo físicogetting-started/quickstart.mdx. - Flujos de trabajo basados en Git: Las modificaciones en la estructura de navegación, la incorporación de nuevas páginas y los ajustes cromáticos se gestionan mediante ramas y Pull Requests estándar, permitiendo revisiones de código y despliegues de vista previa.
- Sincronización con el editor web: Cuando miembros del equipo utilizan el editor visual en la nube de Mintlify para reordenar páginas arrastrando y soltando, la plataforma genera automáticamente commits de Git que actualizan
docs.json.
2. Configuración de marca personalizada e identidad visual
Mintlify permite alinear la documentación con los sistemas de diseño corporativos sin necesidad de inyectar reglas CSS frágiles. Las propiedades visuales se configuran en el nivel superior de docs.json.
Temas de diseño (Theme)
Mintlify ofrece una colección de temas preconfigurados mediante la propiedad theme:
mint: El diseño clásico y probado, idóneo para software de código abierto y utilidades generales.maple: Una estética limpia y contemporánea, ampliamente adoptada por plataformas SaaS y herramientas de inteligencia artificial.palm: Una maquetación densa y estructurada para entornos de tecnología financiera y arquitecturas empresariales complejas.willow: Un estilo minimalista enfocado en la lectura libre de distracciones.- Opciones adicionales incluyen
linden,almond,aspen,sequoiayluma.
Paleta de colores y modo oscuro
El objeto colors define los colores principales de la marca, asegurando niveles de contraste adecuados tanto en modo claro como en modo oscuro:
"colors": {
"primary": "#2563EB",
"light": "#60A5FA",
"dark": "#1D4ED8"
}
primary: Color principal de la marca, utilizado en modo claro para enlaces, estados activos y botones destacados.light: Tono de énfasis para modo oscuro, optimizado para contrastar con fondos negros o grises profundos.dark: Empleado para efectos de desplazamiento (hover) y acciones secundarias en ambas modalidades.
Logotipo adaptativo y Favicon
Para garantizar que la marca luzca nítida sobre fondos claros y oscuros, se deben suministrar gráficos vectoriales SVG independientes, junto con una URL de redirección:
"logo": {
"light": "/images/logo-light.svg",
"dark": "/images/logo-dark.svg",
"href": "https://acme.com"
},
"favicon": "/images/favicon.svg"
Si se omite logo.href, hacer clic en el logotipo redirige automáticamente a la página de inicio de la documentación.
Tipografía, iconos y fondo
- Fuentes tipográficas: En la propiedad
fontses posible indicar fuentes de Google Fonts por nombre de familia (como"Inter"o"Fira Code"), las cuales se cargan de forma asíncrona. Asimismo, se pueden definir fuentes autohospedadas en formato.woff2y diferenciar tipografías entre títulos (fonts.heading) y cuerpo de texto (fonts.body). - Bibliotecas de iconos: Mintlify integra nativamente Font Awesome, Lucide y Tabler. Al definir
"icons": { "library": "lucide" }, se pueden asignar nombres de iconos directos como"book-open"o"terminal", además de admitir SVG en línea o emoticonos. - Texturas de fondo: La propiedad
"background": { "decoration": "gradient" }o"grid"añade patrones sutiles sobre el lienzo. - Bloqueo de modo: Si la identidad corporativa exige un entorno exclusivamente oscuro, se puede configurar
"appearance": { "default": "dark", "strict": true }, lo que oculta el interruptor de cambio de tema a los usuarios.
3. Estructuración de barras laterales: Grupos, anidamiento y páginas raíz
La barra lateral de navegación es el eje central para guiar al lector de forma secuencial. En Mintlify, toda la barra lateral se diseña dentro del objeto navigation en docs.json.
Grupos estándar e iconografía
Un grupo reúne un conjunto de páginas bajo un título común. Cada grupo requiere un nombre de group y un arreglo de pages:
"navigation": {
"groups": [
{
"group": "Primeros pasos",
"icon": "rocket",
"pages": [
"quickstart",
"installation",
"authentication"
]
}
]
}
Anidamiento jerárquico y estados de colapso
A medida que la documentación crece, una lista plana resulta difícil de examinar. Mintlify permite anidar subgrupos dentro del arreglo pages de un grupo superior.
Para evitar sobrecargar visualmente al usuario, se puede controlar el estado de despliegue inicial mediante la propiedad booleana expanded:
{
"group": "Arquitectura central",
"icon": "cpu",
"pages": [
"architecture/overview",
{
"group": "Capa de almacenamiento",
"icon": "database",
"expanded": false,
"pages": [
"architecture/storage/relational",
"architecture/storage/caching"
]
},
{
"group": "Seguridad y cumplimiento",
"icon": "shield-check",
"tag": "NEW",
"pages": [
"architecture/security/rbac",
"architecture/security/encryption"
]
}
]
}
Nota: Los grupos principales del nivel superior siempre se muestran expandidos en la barra lateral; el modificador expanded aplica a los subgrupos anidados.
Títulos de grupo interactivos con páginas raíz (root)
Por defecto, al hacer clic en el título de un grupo en la barra lateral solo se expande o contrae su contenido. Sin embargo, muchas veces se busca que el título funcione como una página de introducción o visión general.
Al definir la propiedad root, el título del grupo se vincula a un archivo MDX:
{
"group": "Referencia de API",
"root": "api/overview",
"pages": [
"api/users",
"api/billing",
"api/webhooks"
]
}
Cuando el usuario pulsa en "Referencia de API", la interfaz carga api/overview.mdx y despliega simultáneamente la lista de endpoints subordinados.
Índices de directorio automáticos (directory)
Para evitar el mantenimiento manual de tablas de contenido, Mintlify proporciona el atributo directory en grupos que cuenten con una página root. El sistema inyecta un índice visual debajo del cuerpo de la página raíz.
Opciones para directory:
"card": Muestra las páginas secundarias como tarjetas interactivas horizontales con títulos y resúmenes."accordion": Presenta la estructura en listas desplegables plegables, ideal para catálogos extensos."none": Desactiva la generación automática (valor por defecto).
Esta propiedad se hereda jerárquicamente hacia los niveles inferiores, permitiendo definir "directory": "card" de manera global y anularlo con "directory": "none" en subsecciones específicas.
4. División de portales multiproducto mediante grupos de pestañas (Tabs)
Cuando un portal de documentación combina guías de arquitectura, documentación exhaustiva de API, SDK en varios lenguajes y notas de versión, condensar todo en una única barra lateral provoca saturación cognitiva. Los grupos de pestañas (Tabs) introducen una navegación horizontal superior que divide el contenido en secciones lógicas e independientes.
Pestañas de navegación a nivel de sitio
Las pestañas crean particiones funcionales completas. Cada pestaña dispone de su propio árbol de barra lateral y su correspondiente espacio de rutas URL.
Se configuran dentro del arreglo navigation.tabs:
"navigation": {
"tabs": [
{
"tab": "Guías",
"icon": "book-open",
"groups": [
{
"group": "Fundamentos",
"pages": ["guides/overview", "guides/quickstart"]
},
{
"group": "Despliegue",
"pages": ["guides/docker", "guides/kubernetes"]
}
]
},
{
"tab": "Referencia API",
"icon": "square-terminal",
"groups": [
{
"group": "Endpoints",
"pages": ["api/v1/auth", "api/v1/payments", "api/v1/webhooks"]
}
]
},
{
"tab": "Librerías SDK",
"icon": "code-2",
"groups": [
{
"group": "Clientes soportados",
"pages": ["sdks/node", "sdks/python", "sdks/go"]
}
]
},
{
"tab": "Registro de cambios",
"icon": "megaphone",
"href": "https://changelog.acme.com"
}
]
}
Al seleccionar pestañas como "Guías", "Referencia API" o "Librerías SDK":
- La barra lateral actualiza instantáneamente su contexto, mostrando exclusivamente las páginas asociadas a esa pestaña.
- La URL del navegador refleja la sección activa.
- Los enlaces externos (definidos con
href) se integran visualmente en la cabecera permitiendo salidas directas a portales externos.
Menús desplegables dentro de pestañas (menu)
Si una pestaña cubre varias líneas de producto independientes, es posible incorporar un arreglo menu dentro de la pestaña para ofrecer un desplegable previo:
{
"tab": "Productos",
"icon": "layers",
"menu": [
{
"item": "Motor de Pagos",
"icon": "credit-card",
"description": "Documentación de liquidación y pasarelas de pago.",
"groups": [
{
"group": "Integración básica",
"pages": ["payments/intro", "payments/checkout"]
}
]
},
{
"item": "Nube de Identidad",
"icon": "key-round",
"description": "Protocolos SSO, OAuth 2.0 y sincronización corporativa.",
"groups": [
{
"group": "Autenticación",
"pages": ["identity/overview", "identity/saml"]
}
]
}
]
}
Anclas globales (Anchors) frente a pestañas
- Tabs (Pestañas): Conmutan entre los dominios principales de documentación, reemplazando íntegramente la barra lateral.
- Global Anchors (Anclas globales): Declaradas en
navigation.global.anchors, son enlaces utilitarios fijos (como "Estado del servicio", "Repositorio GitHub" o "Comunidad en Discord") que permanecen visibles independientemente de la pestaña o página activa.
Distinción clave: Pestañas de sitio vs. componentes <Tabs> en MDX
Es común confundir las pestañas globales con los componentes en MDX:
- Pestañas de navegación global (
docs.json): Gestionan la arquitectura general y la alternancia de barras laterales. - Componentes
<Tabs>en MDX: Son bloques de contenido utilizados para alternar fragmentos de código (por ejemplo, ver un ejemplo en cURL, Node.js o Python). Mintlify sincroniza automáticamente la pestaña activa entre diferentes bloques de una página que compartan los mismos títulos, a menos que se definasync={false}.
5. Ejemplo de configuración integral para entornos de producción
A continuación se muestra un archivo docs.json completo y funcional que integra identidad corporativa, anclas globales, múltiples pestañas, subgrupos jerárquicos y maquetación de tarjetas automáticas:
{
"$schema": "https://mintlify.com/docs.json",
"name": "Documentación CloudScale",
"theme": "maple",
"colors": {
"primary": "#059669",
"light": "#34D399",
"dark": "#047857"
},
"logo": {
"light": "/assets/brand/cloudscale-logo-light.svg",
"dark": "/assets/brand/cloudscale-logo-dark.svg",
"href": "https://cloudscale.dev"
},
"favicon": "/assets/brand/favicon.png",
"appearance": {
"default": "system",
"strict": false
},
"fonts": {
"family": "Inter"
},
"icons": {
"library": "lucide"
},
"background": {
"decoration": "gradient"
},
"navigation": {
"global": {
"anchors": [
{
"anchor": "Estado del sistema",
"icon": "activity",
"href": "https://status.cloudscale.dev"
},
{
"anchor": "Comunidad Slack",
"icon": "messages-square",
"href": "https://cloudscale.dev/slack"
}
]
},
"tabs": [
{
"tab": "Guías del producto",
"icon": "book-open",
"groups": [
{
"group": "Visión general e instalación",
"root": "guides/index",
"directory": "card",
"pages": [
"guides/quickstart",
"guides/architecture",
"guides/cli-tooling"
]
},
{
"group": "Infraestructura",
"icon": "server",
"pages": [
"guides/compute-clusters",
{
"group": "Redes y DNS",
"expanded": false,
"pages": [
"guides/networking/vpc-peering",
"guides/networking/tls-certificates"
]
}
]
}
]
},
{
"tab": "Referencia de API",
"icon": "square-terminal",
"groups": [
{
"group": "Autenticación",
"pages": [
"api/auth/tokens",
"api/auth/service-accounts"
]
},
{
"group": "API de Cómputo",
"root": "api/compute/overview",
"pages": [
"api/compute/instances",
"api/compute/snapshots"
]
}
]
}
]
}
}
6. Prácticas operativas y recomendaciones de equipo
Para garantizar la estabilidad del portal de documentación a medida que los equipos técnicos escalan, se recomienda seguir estas directrices:
- Validación local mediante CLI: Antes de enviar cambios al repositorio, ejecute
npx mintlify deven su entorno local. El servidor detectará de inmediato errores de sintaxis JSON, rutas MDX inexistentes o enlaces rotos. - Coherencia estricta en las rutas: Cada valor en
"pages"debe apuntar a un archivo existente. Si se renombra un archivo físico (comoguides/intro.mdxaguides/overview.mdx), debe actualizarse la referencia correspondiente endocs.jsonen el mismo commit de Git. - Control del contraste visual en modo oscuro: Al definir
colors.primary, no descuide el ajuste fino decolors.light. Es crucial comprobar que los textos y enlaces en modo oscuro cumplan con los estándares de accesibilidad WCAG AA. - Moderar los niveles de anidamiento: Mantenga la jerarquía de la barra lateral en un máximo de dos niveles (grupo principal > subgrupo > página). Un anidamiento excesivo genera desplazamiento horizontal y fricción en pantallas pequeñas; ante contenidos muy ramificados, es preferible utilizar pestañas (Tabs) o menús desplegables.