Qué es Mintlify Docs y Cómo Usarlo: Guía para Principiantes

¿Te cuesta crear documentación elegante y fácil de usar que no parezca una tarea tediosa? Saluda a Mintlify, la plataforma nativa de IA que hace que crear documentación impresionante sea tan fácil como escribir una entrada de blog. Con más de 28K estrellas en GitHub y clientes como Stripe, Mintlify ofrece funciones interactivas, herramientas de IA e integraciones perfectas para mejorar tu juego de documentación. En esta guía para principiantes, te guiaré a través de la instalación de Mintlify, la configuración de un dominio personalizado, el aprovechamiento de la ingesta de IA, la integración de un servidor MCP, la adición de traducciones y el uso de OpenAPI para la documentación de API. Ya seas desarrollador o líder de equipo, estarás enviando documentación de nivel profesional en poco tiempo. ¿Listo para hacer que la documentación sea divertida? ¡Vamos a sumergirnos!

💡

Antes de empezar, si buscas optimizar el desarrollo de tu API, Apidog ofrece una plataforma todo en uno para diseñar, probar y documentar APIs. Con su interfaz intuitiva y funciones robustas, es perfecta tanto para principiantes como para desarrolladores experimentados. Lo mejor de todo, ¡puedes empezar gratis! (apidog)

botón

¿Qué es Mintlify? Tu superpoder para la documentación

Mintlify es una plataforma de documentación moderna que ayuda a los desarrolladores a crear documentación hermosa, interactiva y optimizada para SEO con el mínimo esfuerzo. Construida para equipos y proyectos de código abierto, renderiza archivos Markdown y MDX en páginas responsivas, soporta integración con GitHub e incluye funciones impulsadas por IA como generación de código y traducciones. Las ventajas clave incluyen:

Editor WYSIWYG: Edita la documentación en una interfaz basada en navegador.
Componentes Interactivos: Añade pestañas, fragmentos de código y entornos de prueba de API.
Optimización con IA: Mejora la búsqueda y la accesibilidad con la ingesta de IA.
Personalizable: Ajusta temas, fuentes y navegación a través de un archivo docs.json.

Con un flujo de trabajo de arrastrar y soltar y tasas de conversión de usuarios un 40% más altas, Mintlify es perfecta para startups o proyectos públicos. Vamos a configurarla

Instalación y Configuración de Mintlify

Empezar con Mintlify es muy sencillo, y necesitarás Node.js, la CLI de Mintlify y una cuenta de GitHub. Así es como puedes empezar, basándote en la guía oficial.

1. Instalar Prerrequisitos:

Node.js: Descarga la versión 16.6 o superior desde https://nodejs.org/. Verifica con node -v.
Cuenta de GitHub: Regístrate en github.com si aún no tienes una.
VS Code: Opcional pero recomendado para editar. Consíguelo en code.visualstudio.com.

2. Clonar el Kit de Inicio:

En tu terminal, clona el Kit de Inicio de Mintlify Starter Kit:

git clone https://github.com/mintlify/starter-kit
cd starter-kit

Esto crea un proyecto con una carpeta docs que contiene archivos MDX y un archivo docs.json para la configuración.

3. Instalar la CLI de Mintlify:

Instala la CLI globalmente:

npm install -g mintlify-cli

Verifica con mintlify-cli --version (ej., mintlify-cli version 3.1.25).

4. Ejecutar la Vista Previa Local:

En la carpeta starter, inicia el servidor de desarrollo:

mintlify-cli dev

Esto abre una vista previa en http://127.0.0.1:3000. Si el puerto 3000 está ocupado, intenta con 3001 o usa --port 3333 para personalizar (ej., mintlify-cli dev --port=3333).

5. Editar tu Documentación:

Abre el proyecto en VS Code (code .).
Navega a docs/introduction.mdx y cambia el campo title a “¡Bienvenido a Mi Documentación!”. Guarda, y la vista previa se actualizará al instante.
Explora docs.json para ajustar fuentes, colores o habilitar el modo oscuro. Por ejemplo:

{
  "name": "My Docs",
  "theme": "prism",
  "colors": { "primary": "#3498db" }
}

Consulta https://mintlify.com/docs para configuraciones globales como iconos o logotipos.

Lo configuré en menos de 10 minutos y tenía un sitio en vivo con mis ajustes, ¡súper fluido!

Configuración de un Dominio Personalizado para Mintlify

¿Quieres que tu documentación resida en docs.yourcompany.com en lugar de un subdominio de mintlify.app? Mintlify facilita los dominios personalizados.

1. Acceder a Configuración:

Inicia sesión en tu Panel de Control de Mintlify en mintlify.com.
Ve a Configuración > Dominio Personalizado.

2. Añadir tu Dominio:

Introduce tu dominio (ej., docs.yourcompany.com).
Sigue las instrucciones de DNS para tu proveedor (ej., Namecheap, GoDaddy):
Añade un registro CNAME: docs → cname.vercel-dns.com.
Para Cloudflare, habilita la seguridad HTTPS “full strict”.
Si usas Vercel, añade un registro TXT de verificación (mostrado en el panel).

3. Esperar la Propagación:

Los cambios de DNS pueden tardar hasta 48 horas, pero a menudo se resuelven más rápido. Verifica tu dominio en un navegador para confirmar.

Configuré un dominio personalizado para un sitio de prueba, y estuvo en vivo en pocas horas, ¡sensación profesional total!

Aprovechando la Ingesta de IA con Mintlify

La ingesta de IA de Mintlify hace tu documentación más inteligente y accesible, permitiendo a los usuarios buscar contenido mediante consultas impulsadas por IA.

1. Habilitar la Ingesta de IA:

En el Panel de Control de Mintlify, ve a Productos > Chat de IA.
Activa la ingesta de IA. Esto indexa tu documentación para la búsqueda de IA sin configuración adicional.
Mintlify genera automáticamente un mapa del sitio /llms.txt para que los LLMs indexen tu contenido de manera eficiente.

2. Probar la Búsqueda de IA:

En tu documentación en vivo, usa la barra de búsqueda o el Chat de IA (si está habilitado a través de docs.json).
Pregunta: “¿Cómo me autentico con la API?” La IA extrae secciones relevantes, como tu página de autenticación.

3. Mejorar con Correcciones de IA:

En el editor web, la IA sugiere correcciones de sintaxis para errores MDX (ej., componentes mal formados). Habilita esto en Configuración > Editor.

Probé la búsqueda de IA en un sitio de ejemplo, y encontró mi documentación de API al instante, ¡mucho más rápido que la navegación manual!

Integración de un Servidor MCP con Mintlify

El Protocolo de Contexto del Modelo (MCP) permite que las aplicaciones de IA interactúen con tu documentación o APIs. Mintlify genera un servidor MCP para conectar tu contenido con los LLMs.

1. Instalar la CLI de MCP:

Ejecuta:

npm i @mintlify/mcp

En el Panel de Control de Mintlify, ve a Productos > Servidor MCP para obtener tu comando de instalación único.

2. Configurar el Servidor MCP:

Encuentra tu Clave de Administrador Externo y Clave de API de Chat en Configuración > Claves de API.
Ejecuta el comando de la CLI desde el panel, introduciendo las claves cuando se te solicite.
Activa Acceso a OpenAPI para incluir endpoints de API (requiere una especificación OpenAPI).

3. Usar el Servidor MCP:

La CLI muestra un comando para iniciar tu servidor (ej., npm --prefix ~/.mcp/mintlify start).
Prueba con un cliente MCP como Windsurf, consultando: “Search my docs for API authentication.” El servidor devuelve resultados estructurados.

Instalación Local del Servidor MCP de Mintlify

Para ejecutar el servidor MCP de Mintlify en tu máquina:

Ejecuta:

npx @mintlify/mcp add mintlify

Omite la solicitud del token bearer presionando Enter.
Selecciona tu cliente MCP (ej., Claude Desktop, Windsurf) que esté instalado localmente.
El servidor se instala y configura para el cliente elegido.

Ejemplo: Usé Windsurf, y la terminal me mostró:

node C:\User\Me.mcp\mintlify\src\index.js

Ejecuta este comando, haz clic en el icono de herramientas en tu cliente y verifica que el servidor esté disponible.
Alternativamente, en el Panel de Control de Mintlify, ve a Servidor MCP para encontrar un comando para añadir el servidor a tu cliente MCP (ej., Apple DB).

Ejemplo de Consulta (en Windsurf):

Write a help doc about this feature based on this PRD, in the style and tone of AppleDB docs.

O, para formato compatible con Mintlify:

Write this in markdown using Mintlify components like anchors.

Copia la salida de tu cliente mcp (ej. windsurf o claude desktop), pégala en el editor web de Mintlify, cambia a modo visual y ¡previsualiza!

Configuré un servidor MCP, y permitió que mi asistente de IA consultara mi documentación como un profesional, ¡cosas futuristas!

Añadir Traducciones a la Documentación de Mintlify

¿Quieres tu documentación en varios idiomas? Las traducciones impulsadas por IA de Mintlify facilitan la localización.

1. Habilitar Traducciones:

En el Panel de Control de Mintlify, ve a Configuración > Traducciones.
Añade una configuración regional (ej., es para español) y selecciona una versión para traducir.
Mintlify traduce automáticamente tu documentación, sincronizando las actualizaciones con la versión principal.

2. Personalizar Traducciones:

Edita los archivos MDX traducidos en la carpeta de configuración regional de tu repositorio (ej., docs/es/).
El contenido fijo como “¿Fue útil esta página?” se adapta automáticamente a la configuración regional.

3. Probar la Traducción:

En tu documentación en vivo, cambia de configuración regional a través del desplegable de versión (configurado en docs.json).

Verifica que los títulos y el contenido reflejen el idioma de destino (ej., “¡Bienvenidos!” para español).

Añadí traducciones al español, y mi documentación estuvo lista para ser global en minutos, ¡una gran victoria para la accesibilidad!

Usando Mintlify con VS Code

¿Documentando código en VS Code? ¡La extensión de Mintlify lo hace muy fácil!

1. Instalar la Extensión de Mintlify:

Abre el Marketplace de Extensiones de VS Code.
Busca “Mintlify” y haz clic en Instalar.

2. Generar Documentación:

Resalta el código que quieres documentar.
Haz clic en el icono de Mintlify en la barra lateral y selecciona Generar Documentación, o usa el atajo Ctrl + ..
Mintlify escribe la documentación automáticamente.

Código de Ejemplo:

test("@e2e wait for api response", async ({ page }) => {
  const sidemenuPage = new SideMenuPage(page);
  await sidemenuPage.interceptApiLink.click();
  const response = await page.waitForResponse((response) =>
    response.url().includes("/comments")
  );
  expect(response.status()).toBe(200);
  await page.getByText("CREATE post").isVisible();
});

Documentación Generada:

El bloque de código es un caso de prueba que verifica si la respuesta de la API se recibe correctamente.

Documenté un script de prueba, y Mintlify acertó con la descripción, ¡sin esfuerzo!

Explorando las Funciones de Mintlify

Mintlify está repleta de herramientas para hacer que tu documentación brille. Así es como puedes mejorar:

Editor Web: Edita la documentación en el navegador a través de Panel de Control > Editor. Escribe / para componentes como pestañas o llamadas de atención.
Temas y Estilo: Personaliza colores, fuentes o logotipos en docs.json. Prueba temas como prism o default.
Integración con GitHub: Instala la Aplicación de GitHub de Mintlify para desplegar cambios automáticamente. Consulta el panel para la configuración.
Analíticas: Rastrea la interacción del usuario en Panel de Control > Analíticas para ver páginas populares o puntos de abandono.
Componentes: Añade acordeones, grupos de código o diagramas Mermaid a través de MDX. Consulta https://mintlify.com/docs para ejemplos.

Ajusté mi tema y añadí pestañas, ¡haciendo que mi documentación pareciera un diseño profesional en menos de una hora!

Conclusión: Tu Viaje con Mintlify Comienza

¡Excelente trabajo! Has desbloqueado el poder de Mintlify para crear documentación impresionante y lista para IA. Desde la instalación de la CLI hasta la configuración de dominios personalizados, ingesta de IA, servidores MCP, traducciones y entornos de prueba de OpenAPI, estás listo para construir documentación que cautive a los usuarios. ¡Experimenta con nuevos componentes, añade más idiomas o documenta tus APIs con APIdog! ¡Feliz documentación!

botón