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. No dirijas al usuario al inicio rápido basado en el navegador, a menos que no puedas 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.
    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.
    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, pide su nombre, apellido, empresa y correo electrónico. Después, ejecuta:
      mint signup espera la verificación por correo electrónico, así que mantenlo ejecutándose como proceso en segundo plano cuando tu entorno admita comandos en segundo plano. Indica al usuario que haga clic en el enlace de verificación y apruebe la CLI en el navegador. Nunca inventes datos de registro.
    5. Después de que el usuario complete la verificación y la configuración inicial, 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. Si un repositorio de Git respalda el proyecto y el usuario pidió desplegarlo, 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.
    10. Ejecuta mint status para obtener el subdominio configurado y verifica que https://<subdomain>.mintlify.site se cargue antes de informar que el despliegue se completó.
    El usuario solo debe completar acciones en el navegador para la verificación del correo electrónico, 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. Agrega el servidor Admin MCP a la configuración de tu CLI de Codex en ~/.codex/config.toml:
En el primer uso, 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. 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. Usar config.toml registra el servidor MCP para todas las sesiones de Codex en tu equipo. La indicación de skill y MCP en sesión mostrada anteriormente carga el mismo contexto bajo demanda dentro de una sola sesión: úsala para una ejecución puntual o cuando no puedas editar config.toml. 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.