Escribe documentación con Codex

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.

Requisitos previos:

• Una cuenta de OpenAI con acceso a Codex

Configuración:

1. Instala la CLI de Codex:

npm install -g @openai/codex

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.

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.

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.

# Mintlify documentation project

## Project context

- This is a documentation project on the Mintlify platform
- We use MDX files with YAML frontmatter
- Navigation is configured in `docs.json`
- We follow technical writing best practices

## Writing standards

- Use second person ("you") for instructions
- Write in active voice and present tense
- Use sentence case for headings ("Getting started", not "Getting Started")
- Start procedures with prerequisites
- Include expected outcomes for major steps
- Keep sentences concise but informative
- Never use marketing language ("powerful", "seamless", "robust")

## Required page structure

Every page must start with frontmatter:

---
title: "Clear, specific title"
description: "Concise description for SEO and navigation."
keywords: ["relevant", "keywords", "here"]
---

## Mintlify components

### docs.json

- Refer to the [docs.json schema](https://mintlify.com/docs.json) when modifying navigation or site settings

### Callouts

- `<Note>` for helpful supplementary information
- `<Warning>` for important cautions and breaking changes
- `<Tip>` for best practices and expert advice
- `<Info>` for neutral contextual information
- `<Check>` for success confirmations

### Code examples

- All code blocks must have a language tag
- Use `<CodeGroup>` for multiple language examples
- Use `<RequestExample>` and `<ResponseExample>` for API docs

### Procedures

- Use `<Steps>` for sequential instructions
- Include verification steps with `<Check>` when relevant

### Content organization

- Use `<Tabs>` for platform-specific content
- Use `<Accordion>` for progressive disclosure
- Use `<Card>` and `<CardGroup>` for highlighting content
- Wrap images in `<Frame>` with descriptive alt text

## Internal links

Use root-relative paths: `/guides/quickstart`, not `../quickstart` or full URLs.

## Quality checklist

Before finishing any documentation task:
- Verify all code blocks have language tags
- Check that frontmatter includes title, description, and keywords
- Confirm internal links use root-relative paths
- Read changes aloud to catch awkward phrasing

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.

Redacción de contenido nuevo:

Crea una nueva página en guides/authentication.mdx que explique cómo autenticarse con nuestra API. Incluye ejemplos de código en JavaScript y Python.

Mejorar el contenido existente:

Revisa docs/quickstart.mdx y sugiere mejoras para mayor claridad. Concéntrate en hacer que los pasos sean más fáciles de seguir y en asegurar que los componentes se usen correctamente.

Actualizar la navegación:

Agregué una nueva página en guides/webhooks.mdx. Añádela a la sección Guides en docs.json después de guides/authentication.

Mantener la consistencia:

Verifica si esta nueva página sigue los estándares de redacción definidos en AGENTS.md y señala cualquier problema.

Conecta el servidor MCP de Mintlify a Codex para darle acceso a buscar en la documentación de Mintlify mientras te ayuda a escribir. Cuando conectas el servidor MCP, Codex puede consultar el uso de los componentes y las opciones de configuración sin que tengas que salir de la terminal.

Agrega el servidor MCP a tu configuración global de Codex en ~/.codex/config.toml. Crea el archivo si no existe:

[mcp_servers.mintlify]
url = "https://mintlify.com/docs/mcp"

Para conectarte en su lugar al servidor MCP de tu propio sitio de documentación, reemplaza la URL por el endpoint MCP de tu sitio:

[mcp_servers.my-docs]
url = "https://your-docs.mintlify.site/mcp"

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 MCP y cómo encontrar el endpoint MCP de tu sitio.