Instalar la CLI

Instala la CLI de Mintlify para previsualizar la documentación localmente, probar cambios en tiempo real y detectar errores de compilación antes de desplegar en producción.

​

Requisitos previos

• Node.js v20.17.0+ (se recomiendan versiones LTS)

​

Instalar la CLI

npm

npm i -g mint

​

Crear un nuevo proyecto

Para crear un nuevo proyecto de documentación a partir de la plantilla inicial de Mintlify, ejecuta el siguiente comando:

mint new [directory]

Si no especificas un directorio, la CLI te solicitará crear un nuevo subdirectorio o sobrescribir el directorio actual.

Sobrescribir el directorio actual elimina todos los archivos existentes.

Flag	Descripción
--name	Nombre del proyecto. La CLI lo solicita si no se proporciona.
--theme	Tema del proyecto. La CLI lo solicita si no se proporciona.
--template	Plantilla predefinida. La CLI la solicita si no se proporciona.
--force	Sobrescribir el directorio actual sin solicitar confirmación.

En modo interactivo, la CLI pregunta si deseas elegir un tema o clonar una plantilla. Para omitir el aviso, pasa el flag --template directamente:

mint new my-docs --template <template-name>

Puedes combinar --template con --theme para anular el tema predeterminado de la plantilla:

mint new my-docs --template <template-name> --theme <theme>

Consulta las plantillas disponibles en el repositorio mintlify/templates en GitHub. En modo interactivo, la CLI obtiene y muestra las plantillas disponibles automáticamente.

En entornos no interactivos como pipelines de CI/CD o agentes de codificación IA, debes proporcionar los flags --name y --theme, o el flag --template.

​

Actualizar

Si tu previsualización local no está sincronizada con la documentación desplegada, actualiza la CLI a la última versión:

mint update

Si mint update no está disponible en tu versión, reinstala la CLI con la última versión:

npm

npm i -g mint@latest

​

Formato

Para resaltado de sintaxis y formato de código en archivos MDX, recomendamos usar las siguientes extensiones:

• Cursor, Windsurf, VS Code: Extensión MDX para VS Code y Prettier
• JetBrains: Plugin MDX para IntelliJ IDEA y Prettier

​

Solución de problemas

Error: Could not load the "sharp" module using the darwin-arm64 runtime

Esto puede deberse a una versión desactualizada de Node.js. Intenta lo siguiente:

1. Elimina la versión actual de la CLI de mint: npm uninstall -g mint
2. Actualiza a Node.js v20.17.0+.
3. Reinstala la CLI de mint: npm install -g mint

Problema: Se produce un error desconocido

Solución: Ve a la raíz de tu dispositivo y elimina la carpeta ~/.mintlify. Después, ejecuta mint dev nuevamente.

Error: permission denied

Esto se debe a que no tienes los permisos necesarios para instalar paquetes de Node de forma global.

Solución: Intenta ejecutar sudo npm i -g mint. Cuando se te solicite, ingresa la contraseña que usas para desbloquear tu computadora.

La previsualización local no se ve igual que la documentación en la web

Es probable que esto se deba a una versión desactualizada de la CLI.

Solución: Ejecuta mint update para obtener los últimos cambios.

Paquete mintlify versus mint

Si tienes problemas con el paquete de la CLI, primero ejecuta npm ls -g para ver qué paquetes están instalados globalmente. Si no usas npm, prueba which mint para localizar la instalación.

Si tienes instalados tanto el paquete mint como el paquete mintlify, desinstala mintlify:

npm uninstall -g mintlify
npm cache clean --force
npm i -g mint

La versión del cliente muestra 'none' después de la instalación

Si ejecutas mint version y la versión del cliente se muestra como none, es posible que la CLI no pueda descargar la aplicación cliente debido a un firewall corporativo o VPN.

Solución: Pide a tu administrador de TI que agregue releases.mintlify.com a la lista de permitidos de tu red.

La CLI se conecta a localhost en lugar de a producción al usar npx

En versiones anteriores a 4.0.1125, ejecutar npx mint dev u otros comandos desde un repositorio de documentación podía hacer que la CLI se detectara incorrectamente como una compilación de desarrollo local. Esto provocaba que la CLI apuntara a URLs de localhost en lugar de a la API de producción de Mintlify, lo que generaba errores de conexión o comportamientos inesperados.

Solución: Actualiza a la última versión de la CLI:

npm i -g mint@latest