Saltar al contenido principal
Usa la CLI de Codex de OpenAI para escribir y mantener documentación de Mintlify desde la terminal. Las instrucciones de proyecto en AGENTS.md proporcionan a Codex un contexto persistente sobre tus estándares de documentación, componentes y guía de estilo.

Empezar

Requisitos previos:
  • Una cuenta de OpenAI con acceso a Codex
Configuración:
  1. Instala la CLI de Codex:
  1. ¿Todavía no tienes un sitio? Pide a tu agente que lo configure. Ejecuta codex y pídele que complete el siguiente flujo de trabajo. Después, continúa con el siguiente paso.
    Si el usuario te pide configurar Mintlify, un sitio de documentación o un proyecto local de Mintlify, completa tú mismo el siguiente flujo de trabajo. Pide al usuario únicamente la información o las aprobaciones que no puedas proporcionar. Recomendamos la configuración inicial mediante la CLI. La configuración inicial web en mintlify.com/start también está disponible si el usuario la prefiere o si no puedes ejecutar comandos de terminal.
    1. Ejecuta node --version y confirma que indica Node.js v20.17.0 o posterior. Se prefiere una versión LTS. Anota si es v22.20 o posterior, ya que el paso 9 lo requiere.
    2. Ejecuta mint --version. Si el comando no está disponible, instala la CLI con npm i -g mint o pnpm add -g mint. Si el comando funciona, ejecuta mint update. Luego ejecuta mint instructions new-site para obtener instrucciones de configuración actualizadas y mint instructions para listar los temas para tareas posteriores.
    3. Ejecuta mint status antes de iniciar la autenticación. Si ya muestra una organización, conserva la sesión existente y no crees otra cuenta.
    4. Si el usuario tiene una cuenta, ejecuta mint login. Si no la tiene, no crees una cuenta ahora. Puedes publicar sin cuenta usando mint deploy en el paso 10, y el usuario crea su cuenta cuando reclama el sitio. No ejecutes mint signup por el usuario: cuando un agente lo ejecuta, muestra la guía de registro para agentes y termina sin enviar un correo electrónico de verificación. Si el usuario quiere conectar su propio repositorio de GitHub desde el principio, envíalo a la configuración inicial web en mintlify.com/start.
    5. Después de mint login, ejecuta mint status de nuevo. Confirma que indique su correo electrónico, organización y subdominio. Si la organización existe pero no aparece ningún subdominio, pídele al usuario que termine de seleccionar o conectar un repositorio de GitHub en la pestaña del navegador de configuración inicial. Después, vuelve a intentarlo.
    6. Si el usuario tiene un repositorio de documentación existente, clónalo o ábrelo. Conserva su contenido. Para un proyecto local nuevo, crea la estructura en un directorio nuevo y vacío con mint new <directory> --name <name> --theme <theme> o mint new <directory> --template <template-name>. Pregunta qué tema o plantilla prefiere si no lo ha especificado. No uses --force en un directorio que contenga archivos del usuario.
    7. Ejecuta mint dev --no-open desde el directorio que contiene docs.json como un proceso en segundo plano. Confirma que la URL local se cargue, comunícasela al usuario y detén el proceso cuando ya no sea necesario.
    8. Ejecuta mint validate y mint broken-links. Corrige los problemas causados por tus cambios antes de continuar.
    9. Ofrece conectar el agente de programación del usuario al proyecto. Si acepta y Node.js es v22.20 o posterior, ejecuta mint agent setup --agent <agent> desde el directorio del proyecto, donde <agent> es claude-code, codex o cursor. El comando instala las skills de Mintlify y añade el MCP de administración a la configuración del proyecto del agente. Pasa --agent porque, sin una terminal interactiva, el comando configura todos los agentes que detecta. Después, el usuario completa el inicio de sesión con OAuth en el agente. Consulta mint agent setup.
    10. Publica cuando el usuario pida un sitio en vivo.
    • Con sesión iniciada y un repositorio de Git: haz commit y push de los cambios. Un push a la rama de producción activa un despliegue. No sobrescribas un repositorio existente con contenido inicial.
    • Sin cuenta: desde el directorio que contiene docs.json, ejecuta mint deploy --subdomain <name> y elige un nombre corto basado en el proyecto. Sigue los pasos que muestra: clona el repositorio alojado en un directorio aparte, copia la documentación en su raíz, haz commit y haz push a main con el token de escritura como encabezado Authorization: Bearer solo para ese comando de Git. Nunca muestres el token al usuario, no lo pongas en una URL remota ni cambies los remotos de Git del usuario. Consulta Registro para agentes.
    1. Verifica que https://<subdomain>.mintlify.site se cargue antes de informar que el despliegue se completó.
      • Con sesión iniciada y un repositorio de Git: ejecuta mint status para obtener el subdominio. Omite los pasos para reclamar el sitio.
      • Sin cuenta: usa la URL que mostró mint deploy y luego entrega el sitio al usuario. Indícale que el sitio caduca a menos que lo reclame. Pídele la dirección de correo electrónico que debe ser propietaria del sitio y nunca inventes una. Ejecuta mint claim --email <email> desde el mismo directorio y comparte el enlace para reclamarlo. Cuando te devuelva el código que se muestra después de iniciar sesión, ejecuta mint claim --code <code>.
    El usuario solo debe completar acciones en el navegador para reclamar un sitio, la aprobación de OAuth y la conexión o autorización de GitHub. Mantén el control del flujo de trabajo en la terminal y reanúdalo después de cada acción del usuario. Para consultar flags y resolver problemas, usa la referencia de comandos de la CLI.
  2. Ve al directorio de tu documentación.
  3. (Opcional) Añade a tu proyecto el archivo AGENTS.md que aparece más abajo.
  4. Ejecuta codex para iniciar una sesión.
Consulta la documentación de la CLI de Codex para conocer alternativas de instalación y opciones de autenticación.

Usa Codex con Mintlify

Codex lee archivos AGENTS.md de tu repositorio para comprender las reglas y convenciones específicas del proyecto antes de empezar a trabajar. Puedes colocar un AGENTS.md en la raíz de tu repositorio de documentación para darle a Codex contexto sobre los componentes de Mintlify, tus estándares de redacción y cómo estructuras tu documentación. Codex detecta archivos AGENTS.md en varios niveles:
  • Instrucciones globales en ~/.codex/AGENTS.md se aplican a todos tus proyectos.
  • Instrucciones del proyecto en la raíz de tu repositorio (o en cualquier subdirectorio) se aplican al trabajo realizado en ese ámbito.
Codex concatena estos archivos desde la raíz hasta el directorio actual, de modo que las instrucciones a nivel de proyecto amplían o anulan las globales. Crea un AGENTS.md en la raíz de tu repositorio de documentación y haz commit para que todas las personas colaboradoras se beneficien del mismo contexto. Consulta AGENTS.md en la documentación de Codex para conocer todos los detalles.

Ejemplo de AGENTS.md

Este archivo proporciona a Codex contexto sobre los componentes de Mintlify y los estándares de redacción técnica. Personalízalo para tu documentación:
  • Estándares de redacción: Actualiza las pautas de lenguaje para alinearlas con tu guía de estilo.
  • Patrones de componentes: Agrega componentes específicos del proyecto o modifica los ejemplos existentes.
  • Ejemplos de código: Reemplaza los ejemplos genéricos con llamadas y respuestas reales de la API para tu producto.
  • Preferencias de estilo y tono: Ajusta la terminología, el formato y otras reglas.
Guárdalo como AGENTS.md en la raíz de tu repositorio de documentación.
AGENTS.md

Trabajar con Codex

Una vez que tengas tu AGENTS.md en su lugar, Codex lo detecta automáticamente cuando inicias una sesión en tu repositorio de documentación.

Ejemplos de indicaciones

Redacción de contenido nuevo:
Mejorar el contenido existente:
Actualizar la navegación:
Mantener la consistencia:

Mejora con el servidor MCP

Conecta el Admin MCP a Codex para darle acceso de escritura a tu contenido y configuración de Mintlify. Para instalar los skills de Mintlify y configurar el Admin MCP en un solo paso, ejecuta mint agent setup en tu directorio de docs. El comando muestra el comando codex mcp login para completar el inicio de sesión OAuth.
Para conectar solo el Admin MCP: Agrega el servidor Admin MCP con la CLI de Codex:
Codex abre una ventana del navegador para completar el inicio de sesión OAuth. Tras autenticarte, Codex reutiliza la sesión en las llamadas posteriores. Si el inicio de sesión no comienza, ejecuta codex mcp login mintlify-admin. El comando agrega el servidor a tu configuración de Codex en ~/.codex/config.toml. Para editar el archivo de configuración directamente, agrega:
Consulta la documentación de Codex MCP para más detalles. Reinicia tu sesión de codex para que el cambio de configuración surta efecto. Para confirmar que el servidor MCP está conectado, pregúntale a Codex Which MCP servers do you have access to?: debería enumerar la entrada que acabas de añadir. Consulta Model Context Protocol para obtener más información sobre los servidores Search MCP y cómo encontrar el endpoint MCP de tu sitio.