Write documentation with Codex

Use OpenAI’s Codex CLI to write and maintain Mintlify documentation from the terminal. Project instructions in AGENTS.md give Codex persistent context about your documentation standards, components, and style guide.

Getting started

Prerequisites:

An OpenAI account with access to Codex

Setup:

Install the Codex CLI:

npm install -g @openai/codex

Navigate to your docs directory.
(Optional) Add the AGENTS.md file below to your project.
Run codex to start a session.

See the Codex CLI documentation for installation alternatives and authentication options.

Use Codex with Mintlify

Codex reads AGENTS.md files from your repository to understand project-specific rules and conventions before it starts working. You can place an AGENTS.md at the root of your docs repo to give Codex context about Mintlify components, your writing standards, and how you structure your documentation. Codex discovers AGENTS.md files at multiple levels:

Global instructions in ~/.codex/AGENTS.md apply to all your projects.
Project instructions in your repo root (or any subdirectory) apply to work done in that scope.

Codex concatenates these files from root to the current directory, so project-level instructions extend or override global ones. Create an AGENTS.md at the root of your docs repo and commit it so all contributors benefit from the same context. See AGENTS.md in the Codex documentation for complete details.

Example AGENTS.md

This file gives Codex context about Mintlify components and technical writing standards. Customize it for your documentation:

Writing standards: Update language guidelines to match your style guide.
Component patterns: Add project-specific components or modify existing examples.
Code examples: Replace generic examples with real API calls and responses for your product.
Style and tone preferences: Adjust terminology, formatting, and other rules.

Save this as AGENTS.md at the root of your docs repo.

AGENTS.md

# 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

Working with Codex

Once your AGENTS.md is in place, Codex picks it up automatically when you start a session in your docs repo.

Example prompts

Writing new content:

Create a new page at guides/authentication.mdx explaining how to authenticate with our API. Include code examples in JavaScript and Python.

Improving existing content:

Review docs/quickstart.mdx and suggest improvements for clarity. Focus on making the steps easier to follow and ensuring components are used correctly.

Updating navigation:

I added a new page at guides/webhooks.mdx. Add it to the Guides section in docs.json after guides/authentication.

Maintaining consistency:

Check whether this new page follows the writing standards in AGENTS.md and flag any issues.

Enhance with MCP server

Connect the Mintlify MCP server to Codex to give it access to search the Mintlify documentation while helping you write. When you connect the MCP server, Codex can look up component usage and configuration options without you leaving the terminal. Add the MCP server to your global Codex config at ~/.codex/config.toml:

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

To connect to your own documentation site’s MCP server instead, replace the URL with your site’s MCP endpoint:

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

See Model Context Protocol for more information about MCP servers and how to find your site’s MCP endpoint.

​Getting started

​Use Codex with Mintlify

​Example AGENTS.md

​Working with Codex

​Example prompts

​Enhance with MCP server