> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify-mintlify-d32b5473.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Documentación headless con un frontend personalizado

> Crea un frontend de documentación headless con Astro usando Mintlify para la gestión de contenido, búsqueda con IA y funciones de asistente.

El modo headless de Mintlify 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 tu propio frontend personalizado con [Astro](https://astro.build) y renderizar tu contenido MDX y la configuración de `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.

<Expandable title="Feature availability for headless projects">
  | Feature                                     | Availability  | Notes                                                                                                                                                                                                |
  | ------------------------------------------- | ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
  | Mintlify components                         | Included      | Usa componentes como `<Card>`, `<Steps>` y `<Tabs>` en tus archivos MDX sin importarlos.                                                                                                             |
  | Content processing                          | Included      | La integración `@mintlify/astro` lee tu `docs.json` y los archivos MDX y los procesa en tiempo de compilación.                                                                                       |
  | Search                                      | Included      | El componente `SearchBar` se conecta a la API de búsqueda de Mintlify usando el subdominio de tu proyecto.                                                                                           |
  | AI assistant                                | Included      | El componente `Assistant` proporciona una interfaz de chat con IA impulsada por tu contenido.                                                                                                        |
  | Layouts and styling                         | Custom build  | Header, footer, barra lateral, tabla de contenidos, plantillas de página y todo el CSS. La plantilla inicial incluye ejemplos construidos con Tailwind CSS.                                          |
  | Routing and navigation                      | Custom build  | Una ruta comodín de Astro renderiza cada página. Usa `resolvePageData()` y `unwrapNav()` de `@mintlify/astro/helpers` para resolver el estado de navegación desde `docs.json`.                       |
  | Deployment and hosting                      | Custom build  | Despliega tu sitio de Astro en cualquier proveedor de alojamiento.                                                                                                                                   |
  | SEO                                         | You build     | Las meta tags, las etiquetas Open Graph, el sitemap y `robots.txt` son tu responsabilidad.                                                                                                           |
  | Third-party integrations                    | Custom build  | Agrega integraciones directamente a tu diseño de Astro. Las herramientas configuradas en `docs.json` para proyectos alojados no aplican en modo headless.                                            |
  | `llms.txt`, `llms-full.txt`, and `skill.md` | Custom build  | Para proyectos headless, debes generar y servir estos archivos tú mismo.                                                                                                                             |
  | Dashboard analytics                         | Custom build  | Si usas el componente `Assistant`, las analíticas de uso del assistant están disponibles en tu dashboard. Para el tráfico de páginas, agrega tu propio proveedor de analíticas a tu diseño de Astro. |
  | Web editor                                  | Not available | Requiere el entorno de renderizado alojado de Mintlify.                                                                                                                                              |
  | Authentication and password protection      | Not available | Solo disponible para sitios alojados en un subdominio de Mintlify o un dominio personalizado apuntando a Mintlify.                                                                                   |
  | API playground                              | Not available | Solo disponible para sitios alojados en la plataforma de Mintlify.                                                                                                                                   |
  | User feedback                               | Not available | La función de feedback de página es parte de la capa de renderizado alojada de Mintlify.                                                                                                             |
  | Preview deployments                         | Not available | Usa el entorno de vista previa de tu proveedor de alojamiento.                                                                                                                                       |
  | PDF export                                  | Not available | No disponible para proyectos headless.                                                                                                                                                               |
</Expandable>

<div id="prerequisites">
  ## Requisitos previos
</div>

* Una [cuenta de Mintlify](https://dashboard.mintlify.com)
* Una [cuenta de GitHub](https://github.com)
* [Node.js](https://nodejs.org) v20.17.0 o posterior (se recomiendan las versiones LTS)
* Familiaridad con [Astro](https://docs.astro.build)

<div id="set-up-your-project">
  ## Configura tu proyecto
</div>

<Steps>
  <Step title="Crea un repositorio a partir de la plantilla inicial">
    Ve al repositorio [mintlify-astro-starter](https://github.com/mintlify/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.
  </Step>

  <Step title="Regístrate en Mintlify">
    Si no tienes una cuenta de Mintlify, regístrate en [dashboard.mintlify.com/signup](https://dashboard.mintlify.com/signup).
  </Step>

  <Step title="Instala la aplicación de GitHub">
    En la página de [Git settings](https://dashboard.mintlify.com/settings/deployment/git-settings) de tu Dashboard de Mintlify, instala la [Mintlify GitHub app](/es/deploy/github). Si ya tienes instalada la aplicación, desinstálala y vuelve a instalarla para poder conectar tu nuevo repositorio.
  </Step>

  <Step title="Conecta tu repositorio">
    1. En la página de [Git settings](https://dashboard.mintlify.com/settings/deployment/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**.

    <Frame>
      <img src="https://mintcdn.com/mintlify-mintlify-d32b5473/NUEBvF1ZPSEZo9nI/images/guides/astro/repo-settings-light.png?fit=max&auto=format&n=NUEBvF1ZPSEZo9nI&q=85&s=c915eab38c5488cfd4b038f597e38249" alt="Configuración del repositorio en la página Git settings." className="block dark:hidden" width="1768" height="1280" data-path="images/guides/astro/repo-settings-light.png" />

      <img src="https://mintcdn.com/mintlify-mintlify-d32b5473/NUEBvF1ZPSEZo9nI/images/guides/astro/repo-settings-dark.png?fit=max&auto=format&n=NUEBvF1ZPSEZo9nI&q=85&s=9f94cffc537486acef9188d1b76a9ebb" alt="Configuración del repositorio en la página Git settings." className="hidden dark:block" width="1768" height="1280" data-path="images/guides/astro/repo-settings-dark.png" />
    </Frame>
  </Step>

  <Step title="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:

    ```bash .env theme={null}
    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`.

    Genera una clave de API del assistant en la página [API keys](https://dashboard.mintlify.com/settings/organization/api-keys) de tu dashboard. Esta clave de API del assistant empieza por `mint_dsc_`.
  </Step>

  <Step title="Inicia el servidor de desarrollo">
    Instala las dependencias e inicia el servidor de desarrollo local en tu repositorio clonado:

    ```bash theme={null}
    cd path/to/your-repository
    npm install
    npm run dev
    ```

    Tu sitio se estará ejecutando localmente en `http://localhost:4321`.
  </Step>
</Steps>

<div id="how-it-works">
  ## Cómo funciona
</div>

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.

<div id="astro-configuration">
  ### Configuración de Astro
</div>

Configura la integración `mintlify()` en `astro.config.mjs` con la ruta a tu directorio de documentación:

```javascript astro.config.mjs theme={null}
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.

<div id="content-structure">
  ### Estructura del contenido
</div>

El contenido de tu documentación está ubicado en el directorio `docs/`, estructurado igual que en cualquier otro proyecto de Mintlify:

```text theme={null}
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](/es/organize/pages#page-metadata) estándar de Mintlify y pueden usar componentes de Mintlify sin necesidad de importarlos.

<div id="routing-and-navigation">
  ### Enrutamiento y navegación
</div>

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.

<div id="layouts-and-styling">
  ### Diseños y estilos
</div>

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:

| Archivo                              | Función                                          |
| ------------------------------------ | ------------------------------------------------ |
| `src/layouts/Layout.astro`           | Diseño HTML raíz                                 |
| `src/pages/[...slug].astro`          | Plantilla de página y carga de datos             |
| `src/components/Header.astro`        | Encabezado del sitio                             |
| `src/components/Sidebar/`            | Navegación de la barra lateral                   |
| `src/components/TableOfContents.tsx` | Tabla de contenidos en la página                 |
| `src/styles/`                        | Estilos globales, tipografía y paleta de colores |

<div id="connect-search-and-assistant">
  ## Conectar la búsqueda y el assistant
</div>

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

<div id="next-steps">
  ## Próximos pasos
</div>

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.