> ## Documentation Index
> Fetch the complete documentation index at: https://www.mintlify.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Write documentation with Codex

> Configure OpenAI Codex CLI with project instructions and MCP to write Mintlify documentation that follows your style guide and MDX standards.

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:**

1. Install the Codex CLI:

```bash theme={null}
npm install -g @openai/codex
```

2. No site yet? Have your agent set one up. Run `codex` and have it complete the following workflow, then continue with the next step.

   <Accordion title="Agent setup workflow">
     If the user asks you to set up Mintlify, a documentation site, or a local Mintlify project, complete the following workflow yourself. Ask the user only for information or approvals you cannot supply. Do not send the user to the browser-first quickstart unless you cannot run terminal commands.

     1. Run `node --version` and confirm it reports Node.js v20.17.0 or newer, preferring an LTS release.
     2. Run `mint --version`. If the command is unavailable, install the CLI with `npm i -g mint` or `pnpm add -g mint`. If the command succeeds, run `mint update`.
     3. Run `mint status` before starting authentication. If it already shows an organization, keep the existing session and do not create another account.
     4. Run `mint login` if the user has an account. Otherwise, ask for their first name, last name, company, and email, then run:

        ```bash theme={null}
        mint signup \
          --firstName <first-name> \
          --lastName <last-name> \
          --company <company> \
          --email <email>
        ```

        `mint signup` waits for email verification, so keep it running as a background process when your environment supports background commands. Tell the user to click the verification link and approve the CLI in the browser. Never invent signup details.
     5. After the user finishes verification and onboarding, run `mint status` again. Confirm that it reports their email, organization, and subdomain. If the organization exists but no subdomain appears, ask the user to finish selecting or connecting a GitHub repository in the onboarding browser tab, then retry.
     6. If the user has an existing documentation repository, clone or open it. Preserve its content. For a new local project, scaffold into a new, empty directory with either `mint new <directory> --name <name> --theme <theme>` or `mint new <directory> --template <template-name>`. Ask which theme or template they want if they have not specified one. Do not use `--force` on a directory containing user files.
     7. Run `mint dev --no-open` from the directory containing `docs.json` as a background process. Confirm the local URL loads, report it to the user, and stop the process when it is no longer needed.
     8. Run `mint validate` and `mint broken-links`. Fix issues caused by your changes before continuing.
     9. If a Git repository backs the project and the user asked for deployment, commit and push the changes. A push to the production branch triggers a deployment. Do not overwrite an existing repository with starter content.
     10. Run `mint status` to get the configured subdomain, then verify that `https://<subdomain>.mintlify.site` loads before reporting that deployment is complete.

     Have the user complete browser actions only for email verification, OAuth approval, and connecting or authorizing GitHub. Keep ownership of the terminal workflow and resume after each user action. For command flags and troubleshooting, use the [CLI command reference](/docs/cli/commands).
   </Accordion>
3. Navigate to your docs directory.
4. (Optional) Add the `AGENTS.md` file below to your project.
5. Run `codex` to start a session.

See the [Codex CLI documentation](https://developers.openai.com/codex/cli) for installation alternatives and authentication options.

<Tip>
  Once Codex is running, paste the following prompt to load the Mintlify [skill](/docs/ai/skillmd), [search MCP](/docs/ai/model-context-protocol), and [admin MCP](/docs/ai/mintlify-mcp) into the session. This gives Codex full context on Mintlify components and your site's content.
</Tip>

<Prompt description="Install the Mintlify skill and MCP servers for AI coding tools." actions={["copy", "cursor"]}>
  Install the Mintlify skill for context on project structure, components, and documentation best practices:

  npx skills add [https://mintlify.com/docs](https://mintlify.com/docs)

  Add the Mintlify Docs MCP server for documentation search:

  [https://mintlify.com/docs/mcp](https://mintlify.com/docs/mcp)

  Add the Mintlify MCP server for dashboard access and content management:

  [https://mcp.mintlify.com](https://mcp.mintlify.com)
</Prompt>

## 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](https://developers.openai.com/codex/guides/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.

```markdown AGENTS.md theme={null}
# 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**:

```text wrap theme={null}
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**:

```text wrap theme={null}
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**:

```text wrap theme={null}
I added a new page at guides/webhooks.mdx. Add it to the Guides section in docs.json after guides/authentication.
```

**Maintaining consistency**:

```text wrap theme={null}
Check whether this new page follows the writing standards in AGENTS.md and flag any issues.
```

## Enhance with MCP server

Connect the [admin MCP](/docs/ai/mintlify-mcp) to Codex to give it write access to your Mintlify content and settings.

Add the admin MCP server to your Codex CLI config at `~/.codex/config.toml`:

```toml theme={null}
[mcp_servers.mintlify]
url = "https://mcp.mintlify.com"
```

On first use, Codex opens a browser window to complete the OAuth login. After authenticating, Codex reuses the session for subsequent calls.

See the [Codex MCP documentation](https://developers.openai.com/codex/mcp) for more details.

Restart your `codex` session for the config change to take effect. To confirm the MCP server connected, ask Codex `Which MCP servers do you have access to?`. It should list the entry you added.

See [Model Context Protocol](/docs/ai/model-context-protocol) for more information about search MCP servers and how to find your site's MCP endpoint.


## Related topics

- [Write documentation with Cursor](/docs/guides/cursor.md)
- [Write documentation with Devin Desktop](/docs/guides/devin-desktop.md)
- [How to write technical documentation](/docs/guides/style-and-tone.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.