Instalación de la CLI

Instala la CLI para previsualizar y desarrollar tu documentación en local

Instalación de la CLI

Requisito previo: Instala Node.js antes de continuar.

1. Instalar la CLI.

   Ejecuta el siguiente comando para instalar la CLI:

   npm

   npm i -g mint
   

2. Vista previa local.

   Ve a tu directorio de documentación (donde se encuentra el archivo docs.json) y ejecuta el siguiente comando:

   mint dev
   

   Una vista previa local de tu documentación estará disponible en http://localhost:3000.

Como alternativa, si no quieres instalar la CLI globalmente, puedes ejecutar un script de una sola vez:

npx mint dev

Actualizaciones

Si tu vista previa local no coincide con lo que ves en la web en la versión de producción, actualiza tu CLI local:

mint update

Si el comando mint update no está disponible en tu versión local, reinstala la CLI con la versión más reciente:

npm

npm i -g mint@latest

Puertos personalizados

De forma predeterminada, la CLI usa el puerto 3000. Puedes personalizar el puerto con la opción --port. Para ejecutar la CLI en el puerto 3333, por ejemplo, usa este comando:

mint dev --port 3333

Si intentas usar un puerto que ya está en uso, se empleará el siguiente puerto disponible:

El puerto 3000 ya está en uso. Probando con 3001.

Vista previa como un grupo específico

Si utilizas Autenticación parcial para restringir el acceso a tu documentación, puedes obtener una vista previa como un grupo de autenticación específico usando la opción --group [groupname].

Por ejemplo, si tienes un grupo llamado admin, puedes obtener una vista previa como miembro de ese grupo con el comando:

mint dev --group admin

Comandos adicionales

Si bien mint dev es el comando más utilizado, existen otros comandos que puedes usar para gestionar tu documentación.

Detectar enlaces rotos

La CLI puede ayudarte a validar los enlaces de referencia incluidos en tu documentación. Para identificar enlaces rotos, utiliza el siguiente comando:

mint broken-links

Comprobar la especificación de OpenAPI

Puedes usar la CLI para verificar tu archivo de OpenAPI en busca de errores con el siguiente comando:

mint openapi-check <openapiFilenameOrUrl>

Puedes proporcionar un nombre de archivo (p. ej., ./openapi.yaml) o una URL (p. ej., https://petstore3.swagger.io/api/v3/openapi.json).

Renombrar archivos

Puedes renombrar y actualizar todas las referencias a archivos usando el siguiente comando:

mint rename <oldFilename> <newFilename>

Migrar páginas de endpoints en MDX

Puedes migrar páginas de endpoints en MDX a páginas autogeneradas a partir de tu especificación de OpenAPI con el siguiente comando:

mint migrate-mdx

Este comando convierte páginas individuales de endpoints en MDX en páginas autogeneradas definidas en tu docs.json, mueve el contenido MDX a la extensión x-mint de tu especificación de OpenAPI y actualiza la navegación. Consulta Migrating from MDX para obtener información detallada.

Formato

Durante el desarrollo local, recomendamos usar extensiones en tu IDE para reconocer y dar formato a archivos MDX.

Si usas Cursor, Windsurf o VS Code, te recomendamos la extensión MDX para VS Code para el resaltado de sintaxis y Prettier para el formateo de código.

Si usas JetBrains, te recomendamos el complemento MDX para IntelliJ IDEA para el resaltado de sintaxis y configurar Prettier para el formateo de código.

Solución de problemas

Error: No se pudo cargar el módulo «sharp» usando el runtime darwin-arm64

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

1. Desinstala la versión actual del CLI de mint: npm uninstall -g mint
2. Actualiza a Node.js.
3. Vuelve a instalar el CLI de mint: npm install -g mint

Problema: Error desconocido

Solución: Ve al directorio raíz de tu usuario y elimina la carpeta ~/.mintlify. Luego, vuelve a ejecutar mint dev.

Error: permiso denegado

Esto ocurre por no tener permisos para instalar paquetes de Node globalmente.

Solución: Prueba con sudo npm i -g mint. Se te pedirá tu contraseña: la misma que usas para desbloquear tu computadora.

La vista previa local no se ve igual que mis docs en la web

Probablemente se deba a una versión desactualizada del CLI.

Solución: Ejecuta mint update para obtener los cambios más recientes.

mintlify vs. paquete mint

Si tienes algún problema con el paquete del CLI, primero ejecuta npm ls -g. Este comando muestra qué paquetes están instalados globalmente en tu máquina.

Si no usas npm o no lo ves en la lista con -g, prueba which mint para localizar la instalación.

Si tienes un paquete llamado mint y otro llamado mintlify instalados, deberías desinstalar mintlify.

1. Desinstala el paquete antiguo:

  npm uninstall -g mintlify

2. Limpia la caché de npm:

  npm cache clean --force

3. Vuelve a instalar el paquete nuevo:

npm i -g mint