Saltar al contenido principal
Un frontend personalizado te permite controlar cómo se ve y se comporta tu documentación mientras usas Mintlify para gestionar tu contenido. En lugar de usar el frontend alojado de Mintlify, puedes crear el tuyo con Astro y renderizar tu contenido MDX y la configuración de docs.json como quieras. Esto es útil cuando necesitas control total sobre el diseño, la estructura o el comportamiento de tu documentación. Por ejemplo, para que coincida con un sistema de diseño existente o para incrustar la documentación en un sitio más grande. La integración @mintlify/astro lee tu configuración docs.json y el contenido MDX en tiempo de compilación, y luego procesa todo en un formato que Astro puede renderizar. Usa tus propios layouts, componentes y estilos por encima de ello. Con un frontend personalizado, puedes seguir usando componentes de Mintlify sin importarlos y seguirás contando con la infraestructura de publicación, búsqueda e IA. Esta guía te guía paso a paso para configurar un nuevo proyecto con la plantilla inicial y ponerlo a funcionar en local.

​
Requisitos previos

​
Configura tu proyecto

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 dashboard.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

  1. En la página de Git settings, selecciona el repositorio que creaste a partir de la plantilla inicial.
  2. Activa el interruptor Set up as monorepo.
  3. Introduce /docs como la ruta al directorio que contiene tu archivo docs.json.
  4. Haz clic en Guardar cambios.
Configuración del repositorio en la página Git settings.
5

Configura las variables de entorno

Clona tu nuevo repositorio en local y crea un archivo .env en la raíz del proyecto con tus credenciales de Mintlify:
.env
PUBLIC_MINTLIFY_SUBDOMAIN=your-subdomain
PUBLIC_MINTLIFY_ASSISTANT_KEY=your-assistant-api-key
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 https://dashboard.mintlify.com/org-name/domain-name, tu subdominio es domain-name.Si tienes un plan Pro o Enterprise, 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:
cd path/to/your-repository
npm install
npm run dev
Tu sitio se estará ejecutando localmente en http://localhost:4321.

​
Cómo funciona

La integración conecta tres partes: el sistema de compilación de Astro, el contenido en tu directorio docs/ y los paquetes de Mintlify que procesan y renderizan ese contenido.

​
Configuración de Astro

Configura la integración mintlify() en astro.config.mjs con la ruta a tu directorio de documentación:
astro.config.mjs
import { defineConfig } from 'astro/config';
import react from '@astrojs/react';
import mdx from '@astrojs/mdx';
import { mintlify } from '@mintlify/astro';

export default defineConfig({
  integrations: [mintlify({ docsDir: './docs' }), react(), mdx()],
});
En tiempo de compilación, la integración lee tu 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.

​
Estructura del contenido

El contenido de tu documentación está ubicado en el directorio docs/, estructurado igual que en cualquier otro proyecto de Mintlify: 
docs/
├── docs.json          # Configuración de navigation y del sitio
├── index.mdx          # Páginas MDX para contenido
├── quickstart.mdx
└── guides/            # Directorios para organizar páginas
    ├── setup.mdx
    └── troubleshooting.mdx
Los archivos MDX utilizan el frontmatter estándar de Mintlify y pueden usar componentes de Mintlify sin necesidad de importarlos.

​
Enrutamiento y navegación

Una ruta comodín renderiza cada página MDX. El paquete @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.

​
Diseños y estilos

Controlas toda la capa de presentación. La plantilla inicial incluye diseños, una barra lateral, una tabla de contenidos y estilos creados con Tailwind CSS, pero puedes reemplazar cualquiera de estos con los tuyos propios. Archivos clave para personalizar:
ArchivoFunción
src/layouts/Layout.astroDiseño HTML raíz
src/pages/[...slug].astroPlantilla de página y carga de datos
src/components/Header.astroEncabezado del sitio
src/components/Sidebar/Navegación de la barra lateral
src/components/TableOfContents.tsxTabla de contenidos en la página
src/styles/Estilos globales, tipografía y paleta de colores

​
Conectar la búsqueda y el assistant

El assistant está disponible en los planes Pro y Enterprise.
La plantilla inicial incluye componentes de búsqueda y assistant que se conectan a las API de Mintlify usando las variables de entorno que configuras durante la configuración inicial.
  • Search: El componente SearchBar en src/components/SearchBar.tsx realiza consultas a la API de búsqueda de Mintlify.
  • Assistant: El componente Assistant en src/components/Assistant/ proporciona una interfaz de chat con IA que responde preguntas usando el contenido de tu documentación.
Ambos requieren las variables de entorno PUBLIC_MINTLIFY_SUBDOMAIN y PUBLIC_MINTLIFY_ASSISTANT_KEY.

​
Próximos pasos

Después de configurar tu proyecto:
  1. Reemplaza el contenido inicial en docs/ con tus propios archivos MDX y la configuración docs.json.
  2. Personaliza los diseños y estilos para que se ajusten a tu sistema de diseño.
  3. Despliega tu sitio de Astro en tu proveedor de alojamiento preferido.