Instalar la CLI

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

​

Requisitos previos

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

​

Instalar la CLI

npm

npm i -g mint

La CLI se publica en npm como el paquete mint. No instales el paquete heredado mintlify en scripts de instalación ni en pipelines de CI. Si tienes ambos paquetes instalados, consulta Paquete mintlify versus mint.

¿Usas una herramienta de codificación con IA? Copia el siguiente prompt para que tu agente instale la CLI y verifique que funciona.

Instala la CLI de Mintlify de forma global y verifica la instalación.

CopiadoCopiar promptAbrir en Cursor

​

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]

Genera la estructura de un nuevo proyecto de Mintlify.

CopiadoCopiar promptAbrir en Cursor

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

​

Instalar en CI

Para ejecutar comprobaciones de la CLI en un pipeline de integración continua, instala el paquete mint de forma global y luego ejecuta los comandos que necesites. Por ejemplo, este job de GitHub Actions comprueba el formato con mint format y valida la compilación con mint validate:

name: Docs checks

on:
  pull_request:
    paths:
      - "**/*.mdx"
      - "docs.json"

jobs:
  docs-checks:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Install the Mintlify CLI
        run: npm i -g mint
      - name: Check formatting
        run: |
          mint format
          if [ -n "$(git status --porcelain)" ]; then
            echo "Files are not formatted. Run 'mint format' locally and commit the changes."
            exit 1
          fi
      - name: Validate the build
        run: mint validate

mint format reescribe los archivos en su lugar y termina con el código 1 si algún archivo no se puede analizar, por lo que el job comprueba si hay un diff después de ejecutarlo. mint validate termina con un error ante cualquier advertencia o error y no necesita ninguna comprobación adicional.

​

Soporte para editores

Para resaltado de sintaxis, autocompletado y verificación de errores en archivos MDX, usa las siguientes extensiones:

• Cursor, Devin Desktop, VS Code: Extensión Mintlify MDX y Prettier para el formato.
• JetBrains: Plugin MDX para IntelliJ IDEA y Prettier.

También puedes formatear archivos MDX con mint format.

​

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 al directorio 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.js 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 los paquetes mint y 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. Esto puede deberse a un firewall corporativo o a una 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. La CLI apuntaba entonces a URLs de localhost en lugar de a la API de producción de Mintlify. Esto generaba errores de conexión o comportamientos inesperados.

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

npm i -g mint@latest