Skip to main content
Gráfico decorativo que representa la CLI. Usa la CLI para obtener una vista previa de tu documentación de forma local mientras escribes y editas. Revisa los cambios en tiempo real antes de implementar, prueba la apariencia y funcionalidad de tu sitio de documentación y detecta problemas como enlaces rotos o problemas de accesibilidad. La CLI también incluye utilidades para mantener tu documentación, como comandos para cambiar el nombre de archivos, validar especificaciones de OpenAPI y migrar contenido entre formatos.

​
Requisitos previos

  • Node.js v20.17.0+ (se recomiendan las versiones LTS) instalado
  • Git instalado
  • Tu repositorio de documentación clonado localmente

​
Clona tu repositorio

1

Localiza tu repositorio

  1. Ve a la página de Git settings de tu dashboard.
  2. Anota la ubicación de tu repositorio. Tiene uno de estos formatos:
  • mintlify-community/docs-{org-name}-{id} (repositorio alojado en Mintlify)
  • your-org/your-repo (tu propio repositorio de GitHub)
2

Clona tu repositorio

Reemplaza your-org/your-repo por los detalles reales de tu repositorio desde Git settings.
Se requiere la Aplicación de GitHub. Para habilitar implementaciones automáticas cuando hagas push de cambios, debes instalar la Aplicación de GitHub. Consulta GitHub para más información.

​
Instalar la CLI

Ejecuta el siguiente comando para instalar la CLI:

​
Vista previa local

Ve a tu directorio de documentación (donde está el archivo docs.json) y ejecuta:
Una vista previa local de tu documentación está disponible en http://localhost:3000. Como alternativa, si no quieres instalar la CLI de forma global, puedes ejecutar un script de una sola vez:

​
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:
Si intentas ejecutar en un puerto que ya está en uso, la CLI usará el siguiente puerto disponible:

​
Omitir el procesamiento de OpenAPI

Si tienes muchos archivos de OpenAPI, puedes omitir el procesamiento de estos archivos durante el desarrollo local para mejorar el rendimiento usando la opción --disable-openapi:

​
Vista previa como un grupo específico

Si usas 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 --groups [groupname]. Por ejemplo, si tienes un grupo llamado admin, puedes obtener una vista previa como miembro de ese grupo con el comando:

​
Crear un proyecto nuevo

Para crear un proyecto de documentación nuevo, ejecuta el siguiente comando:
Este comando clona el kit inicial en un directorio especificado. Si no se especifica un directorio, la herramienta CLI te pedirá crear un nuevo subdirectorio o sobrescribir el directorio actual.
Si sobrescribes el directorio actual, se eliminarán todos los archivos existentes en él.
La herramienta CLI te pedirá un nombre de proyecto y un tema para completar la configuración de tu proyecto. Puedes ejecutar mint new con las siguientes opciones:
  • --theme: Define el tema del nuevo proyecto.
  • --name: Define el nombre del nuevo proyecto.
  • --force: Sobrescribe el directorio actual si ya existe.
Por ejemplo, para crear un proyecto nuevo en el directorio docs con el nombre my-project y el tema linden, ejecuta el siguiente comando:

​
Actualizar la CLI

Si tu vista previa local no coincide con lo que ves en la versión de producción en la web, actualiza tu CLI local:
Si el comando mint update no está disponible en tu versión local, vuelve a instalar la CLI con la versión más reciente:

​
Comandos adicionales

Identifica los enlaces internos rotos con el siguiente comando:
El comando ignora los archivos que coinciden con los patrones definidos en .mintignore. Los enlaces que apuntan a archivos ignorados se reportan como rotos.

​
Detectar problemas de accesibilidad

Prueba las relaciones de contraste de color y busca texto alternativo faltante en imágenes y videos de tu documentación con el siguiente comando:
Usa flags para detectar problemas de accesibilidad específicos.

​
Verificar la especificación de OpenAPI

Comprueba tu archivo de OpenAPI en busca de errores con el siguiente comando:
Indica un nombre de archivo (por ejemplo, ./openapi.yaml) o una URL (por ejemplo, https://petstore3.swagger.io/api/v3/openapi.json).

​
Renombrar archivos

Renombra y actualiza todas las referencias a archivos con el siguiente comando:

​
Migrar páginas de endpoints en MDX

Migra las páginas de endpoints en MDX a páginas autogeneradas a partir de tu especificación de OpenAPI con el siguiente comando:
Este comando convierte páginas individuales de endpoints en MDX en páginas autogeneradas definidas en tu docs.json, mueve el contenido de MDX a la extensión x-mint en tu especificación de OpenAPI y actualiza tu navegación. Consulta Migración desde 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, recomendamos la extensión MDX para VS Code para el resaltado de sintaxis y Prettier para el formateo de código. Si usas JetBrains, recomendamos el plugin MDX para IntelliJ IDEA para el resaltado de sintaxis y configurar Prettier para el formateo de código.

​
Solución de problemas

Esto puede deberse a una versión desactualizada de Node. Prueba lo siguiente:
  1. Desinstala la versión actualmente instalada de la CLI de mint: npm uninstall -g mint
  2. Actualiza a Node.js.
  3. Reinstala la CLI de mint: npm install -g mint
Solución: Ve al directorio raíz de tu usuario y elimina la carpeta ~/.mintlify. Después, ejecuta mint dev de nuevo.
Esto se debe a no tener los permisos necesarios para instalar paquetes de Node de forma global.Solución: Intenta ejecutar sudo npm i -g mint. Se te pedirá tu contraseña, la misma que usas para desbloquear tu computadora.
Es probable que se deba a una versión desactualizada de la CLI.Solución: Ejecuta mint update para obtener los cambios más recientes.
Si tienes algún problema con el paquete de la 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 instalado, debes desinstalar mintlify.
  1. Desinstala el paquete antiguo:
  1. Limpia la caché de npm:
  1. Reinstala el paquete nuevo:
Si ejecutas mint version y la versión del cliente aparece como none, es posible que la CLI no pueda descargar la aplicación cliente debido a que un firewall corporativo o una VPN está bloqueando la descarga.Solución: Pídele a tu administrador de TI que incluya en la lista de permitidos releases.mintlify.com para habilitar el desarrollo local con la CLI.