mintlify__docs/es/guides/custom-frontend.mdx

---
title: "Crear un frontend personalizado"
sidebarTitle: "Frontend personalizado"
description: "Usa la integración de Astro para renderizar tu documentación con un frontend completamente personalizado mientras utilizas la infraestructura de contenido y de IA de Mintlify."
keywords: ["Astro", "headless", "self-hosted", "custom"]
---

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](https://astro.build) 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.

<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="/images/guides/astro/repo-settings-light.png" alt="Configuración del repositorio en la página Git settings." className="block dark:hidden" />

      <img src="/images/guides/astro/repo-settings-dark.png" alt="Configuración del repositorio en la página Git settings." className="hidden dark:block" />
    </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
    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](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
    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
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
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>

<Note>
  El assistant está disponible en los [planes Pro y Enterprise](https://mintlify.com/pricing).
</Note>

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.