Write documentation with Codex

​

Getting started

• An OpenAI account with access to Codex

1. Install the Codex CLI:

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.
   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. We recommend CLI onboarding. Web onboarding at mintlify.com/start is also available if the user prefers it or you cannot run terminal commands.

   1. Run node --version and confirm it reports Node.js v20.17.0 or newer, preferring an LTS release. Note whether it is v22.20 or newer, which step 9 requires.
   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. Then run mint instructions new-site for current setup guidance, and mint instructions to list topics for later tasks.
   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, don’t create an account now. You can publish without one using mint deploy in step 10, and the user creates their account when they claim the site. Don’t run mint signup for the user: when an agent runs it, it prints the agent signup guide and exits without sending a verification email. If the user wants their own GitHub repository connected from the start, send them to web onboarding at mintlify.com/start.
   5. After mint login, 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. Offer to connect the user’s coding agent to the project. If they agree and Node.js is v22.20 or newer, run mint agent setup --agent <agent> from the project directory, where <agent> is claude-code, codex, or cursor. It installs Mintlify skills and adds the admin MCP to the agent’s project configuration. Pass --agent because without an interactive terminal the command configures every agent it detects. The user completes OAuth sign-in in the agent afterward. See mint agent setup.
   10. Publish when the user asks for a live site.

   • Logged in with a Git repository: commit and push the changes. A push to the production branch triggers a deployment. Do not overwrite an existing repository with starter content.
   • No account: from the directory containing docs.json, run mint deploy --subdomain <name>, choosing a short name based on the project. Follow the steps it prints: clone the hosted repository into a separate directory, copy the docs into its root, commit, and push to main with the write token as an Authorization: Bearer header for that Git command only. Never show the token to the user, put it in a remote URL, or change the user’s own Git remotes. See Agent signup.

   11. Verify that https://<subdomain>.mintlify.site loads before reporting that deployment is complete.
       • Logged in with a Git repository: run mint status to get the subdomain. Skip the claim steps.
       • No account: use the URL that mint deploy printed, then hand the site to the user. Tell them the site expires unless they claim it. Ask for the email address that should own it, and never invent one. Run mint claim --email <email> from the same directory and share the claim link. When they return the code shown after they sign in, run mint claim --code <code>.

   Have the user complete browser actions only for claiming a site, 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.
3. Navigate to your docs directory.
4. (Optional) Add the AGENTS.md file below to your project.
5. Run codex to start a session.

​

Use Codex with Mintlify

• 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.

​

Example AGENTS.md

• 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.

# 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

​

Example prompts

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

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

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

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

​

Enhance with MCP server

mint agent setup --agent codex

codex mcp add mintlify-admin --url https://mcp.mintlify.com

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