docs.json como quieras.
Este enfoque headless es útil cuando necesitas control total sobre el diseño, la estructura o el comportamiento de tu documentación para que coincida con un sistema de diseño existente o para incrustar la documentación en un sitio más grande, mientras sigues usando Mintlify para la publicación, búsqueda, componentes MDX y funciones de IA.
La integración @mintlify/astro lee tu configuración de docs.json y el contenido MDX en tiempo de compilación, y luego procesa todo en un formato que Astro puede renderizar. Crea tu propio diseño, componentes y estilos sobre esta base.
Esta guía te guía paso a paso para configurar un proyecto headless de Mintlify con la plantilla inicial y ponerlo en funcionamiento localmente.
- Una cuenta de Mintlify
- Una cuenta de GitHub
- Node.js v20.17.0 o posterior (se recomiendan las versiones LTS)
- Familiaridad con Astro
- Un proveedor de alojamiento que ejecute código del lado del servidor, como Node.js, para la búsqueda y el assistant
1
Crea un repositorio a partir de la plantilla inicial
Ve al repositorio mintlify-astro-starter en GitHub y haz clic en Use this template para crear un nuevo repositorio en tu cuenta.Clona el repositorio en tu máquina local.
2
Regístrate en Mintlify
Si no tienes una cuenta de Mintlify, regístrate en app.mintlify.com/signup.
3
Instala la aplicación de GitHub
En la página de Git settings de tu Dashboard de Mintlify, instala la Mintlify GitHub app. Si ya tienes instalada la aplicación, desinstálala y vuelve a instalarla para poder conectar tu nuevo repositorio.
4
Conecta tu repositorio
- En la página de Git settings, selecciona el repositorio que creaste a partir de la plantilla inicial.
- Activa el interruptor Set up as monorepo.
- Introduce
/docscomo la ruta al directorio que contiene tu archivodocs.json. - Haz clic en Save changes.
5
Configura las variables de entorno
Clona tu nuevo repositorio en local y crea un archivo Tu subdominio es el nombre de dominio de tu proyecto. Es la parte de la URL de tu dashboard que aparece después del nombre de la organización. Por ejemplo, si la URL de tu dashboard es
.env en la raíz del proyecto con tus credenciales de Mintlify:.env
https://app.mintlify.com/org-name/domain-name, tu subdominio es domain-name.Genera una clave de API del assistant en la página API keys de tu dashboard. Esta clave de API del assistant empieza por mint_dsc_.6
Inicia el servidor de desarrollo
Instala las dependencias e inicia el servidor de desarrollo local en tu repositorio clonado:Tu sitio se estará ejecutando localmente en
http://localhost:4321.docs/ y los paquetes de Mintlify que procesan y renderizan ese contenido.
Configura la integración mintlify() en astro.config.mjs con la ruta a tu directorio de documentación:
astro.config.mjs
docs.json y los archivos MDX desde la ruta docsDir y los procesa en .mintlify/docs/, donde las colecciones de contenido de Astro los incorporan.
Astro prerrenderiza tus páginas como HTML estático. El adaptador de Node.js las sirve y ejecuta las rutas de servidor para la búsqueda y el assistant. El esquema env declara MINTLIFY_ASSISTANT_KEY como un secreto del servidor, por lo que el servidor la lee en tiempo de ejecución y Astro nunca la escribe en el resultado de la compilación.
El contenido de tu documentación está ubicado en el directorio docs/, estructurado igual que en cualquier otro proyecto de Mintlify:
@mintlify/astro/helpers proporciona funciones para resolver el estado de la navegación desde tu docs.json.
resolvePageData(): Devuelve pestañas, navegación de la barra lateral, enlaces de pie de página y anclas para una ruta de página dada.unwrapNav(): Aplana el árbol de navegación en una lista para el renderizado de la barra lateral.
La plantilla inicial incluye componentes de búsqueda y assistant que se conectan a las API de Mintlify a través de rutas de servidor en tu sitio. El navegador nunca llama directamente a las API de Mintlify, por lo que tu clave de API del assistant permanece en tu servidor.
- Search: El componente
SearchBarensrc/components/SearchBar.tsxenvía las consultas a la ruta/api/search. - Assistant: El componente
Assistantensrc/components/Assistant/proporciona una interfaz de chat con IA que responde preguntas usando el contenido de tu documentación. Envía los mensajes a la ruta/api/assistant, que transmite la respuesta de vuelta.
src/pages/api/ y necesitan las variables de entorno PUBLIC_MINTLIFY_SUBDOMAIN y MINTLIFY_ASSISTANT_KEY. Cada ruta añade tu clave de API a la solicitud y la reenvía a Mintlify. Las rutas establecen las opciones de la solicitud, como los filtros de búsqueda, para que los visitantes no puedan cambiarlas.
Cualquiera que pueda abrir tu sitio puede llamar a estas rutas, y cada llamada usa tus créditos del assistant.
La plantilla inicial usa el adaptador de Node.js, por lo que puedes desplegarla en cualquier servicio de alojamiento que ejecute un servidor Node.js. Compila el sitio e inicia el servidor:
PUBLIC_MINTLIFY_SUBDOMAIN antes de compilar. Define MINTLIFY_ASSISTANT_KEY en las variables de entorno de tu proveedor de alojamiento. El servidor de producción no lee tu archivo .env.
Para desplegar en una plataforma como Vercel, Netlify o Cloudflare, reemplaza el adaptador de Node.js en astro.config.mjs por el adaptador de Astro de esa plataforma. La búsqueda y el assistant no funcionan sin un adaptador.
Después de configurar tu proyecto:
- Reemplaza el contenido inicial en
docs/con tus propios archivos MDX y la configuracióndocs.json. - Personaliza los diseños y estilos para que se ajusten a tu sistema de diseño.
- Despliega tu sitio en tu proveedor de alojamiento.