使用 Codex 编写文档

使用 OpenAI 的 Codex CLI 在终端中编写和维护 Mintlify 文档。AGENTS.md 中的项目说明可为 Codex 提供关于你的文档标准、组件和样式指南的持久 context。

开始使用

前置条件：

一个可访问 Codex 的 OpenAI 账户

设置：

安装 Codex CLI：

npm install -g @openai/codex

还没有站点？让你的智能体来创建一个。运行 codex 并让它完成以下工作流，然后继续下一步。
智能体设置工作流
如果用户要求你设置 Mintlify、文档站点或本地 Mintlify 项目，请自行完成以下工作流。只有在你无法自行提供的信息或审批时才询问用户。除非你无法运行终端命令，否则不要让用户转去使用以浏览器为主的快速开始流程。
1. 运行 node --version，确认其报告的 Node.js 版本为 v20.17.0 或更高，优先使用 LTS 版本。
2. 运行 mint --version。如果该命令不可用，请使用 npm i -g mint 或 pnpm add -g mint 安装 CLI。如果命令成功，请运行 mint update。
3. 在开始身份验证之前运行 mint status。如果它已显示某个组织，请保留现有会话，不要再创建新账户。
4. 如果用户已有账户，请运行 mint login。否则，询问用户的名字、姓氏、公司和电子邮件，然后运行：
  mint signup \ --firstName <first-name> \ --lastName <last-name> \ --company <company> \ --email <email>
  mint signup 会等待电子邮件验证，因此如果你的环境支持后台命令，请让它作为后台进程持续运行。告诉用户点击验证链接，并在浏览器中批准 CLI。切勿编造注册信息。
5. 用户完成验证和引导流程后，再次运行 mint status。确认它报告了用户的电子邮件、组织和子域名。如果组织已存在但未显示子域名，请让用户在引导流程的浏览器标签页中完成选择或连接 GitHub 仓库，然后重试。
6. 如果用户已有文档仓库，请克隆或打开它，并保留其中的内容。对于新的本地项目，请使用 mint new <directory> --name <name> --theme <theme> 或 mint new <directory> --template <template-name> 在一个新的空目录中生成项目脚手架。如果用户未指定主题或模板，请询问他们想要哪一个。不要在包含用户文件的目录上使用 --force。
7. 在包含 docs.json 的目录中以后台进程方式运行 mint dev --no-open。确认本地 URL 可以加载，将其告知用户，并在不再需要时停止该进程。
8. 运行 mint validate 和 mint broken-links。在继续之前，修复由你的更改引起的问题。
9. 如果项目由 Git 仓库支持且用户要求部署，请提交并推送更改。推送到生产 branch 会触发部署。不要用起始内容覆盖现有仓库。
10. 运行 mint status 获取已配置的子域名，然后在报告部署完成之前，验证 https://<subdomain>.mintlify.site 可以正常加载。
仅让用户在浏览器中完成电子邮件验证、OAuth 批准以及连接或授权 GitHub 这些操作。由你负责终端工作流，并在每次用户操作后继续执行。有关命令参数和故障排除，请使用 CLI 命令参考。
进入你的文档目录。
（可选）将下面的 AGENTS.md 文件添加到你的项目中。
运行 codex 启动会话。

有关安装替代方案和身份验证选项，请参阅 Codex CLI 文档。

将 Codex 与 Mintlify 配合使用

Codex 会在开始工作之前读取仓库中的 AGENTS.md 文件，以了解项目特定的规则和约定。你可以在文档仓库的根目录中放置一个 AGENTS.md 文件，为 Codex 提供有关 Mintlify 组件、写作标准以及你如何组织文档结构的 context。 Codex 会在多个层级发现 AGENTS.md 文件：

全局说明位于 ~/.codex/AGENTS.md，适用于你的所有项目。
项目说明位于你的仓库根目录（或任何子目录），适用于该范围内的工作。

Codex 会将这些文件从根目录到当前目录依次拼接，因此项目级说明会扩展或覆盖全局说明。在你的文档仓库根目录创建 AGENTS.md 并提交，让所有贡献者都能受益于相同的 context。完整详情请参阅 Codex 文档中的 AGENTS.md。

示例 AGENTS.md

此文件为 Codex 提供有关 Mintlify 组件和技术写作标准的 context。根据你的文档进行自定义：

写作标准：更新语言规范以符合你的风格指南。
组件模式：添加项目特定的组件，或修改现有示例。
代码示例：将通用示例替换为与你的产品相关的真实 API 调用与响应。
风格与语气偏好：调整术语、格式和其他规则。

将其保存为文档仓库根目录中的 AGENTS.md。

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

使用 Codex

完成 AGENTS.md 的配置后，当你在文档仓库中启动会话时，Codex 会自动读取该文件。

示例提示

撰写新对象：

在 guides/authentication.mdx 创建一个新页面，说明如何通过我们的 API 进行身份验证。包含 JavaScript 和 Python 的代码示例。

改进现有对象：

审查 docs/quickstart.mdx 并提出改进清晰度的建议。重点让步骤更易于理解，并确保正确使用组件。

更新导航：

我在 guides/webhooks.mdx 添加了一个新页面。请将其添加到 docs.json 中 Guides 部分的 guides/authentication 之后。

保持一致性：

检查此新页面是否符合 AGENTS.md 中的写作标准，并标记出任何问题。

使用 MCP 服务器增强功能

将管理员 MCP连接到 Codex，使其获得对你的 Mintlify 内容和设置的写入权限。在 ~/.codex/config.toml 中的 Codex CLI 配置里添加管理员 MCP 服务器：

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

首次使用时，Codex 会打开一个浏览器窗口以完成 OAuth 登录。完成认证后，Codex 会在后续调用中复用该会话。详情请参见 Codex MCP 文档。重启你的 codex 会话以使配置更改生效。要确认 MCP 服务器已连接，可向 Codex 提问 Which MCP servers do you have access to?——它应列出你刚才添加的条目。使用 config.toml 会为你计算机上的每个 Codex 会话注册该 MCP 服务器。前面展示的会话内 skill 和 MCP 提示则可以在单个会话中按需加载相同的 context——当你需要一次性运行或无法编辑 config.toml 时，请使用该方式。有关搜索 MCP 服务器以及如何查找你站点 MCP 端点的更多信息，请参阅 Model Context Protocol。

概览

AI

API 文档

最佳实践

Git

使用场景

使用 Codex 编写文档

开始使用

将 Codex 与 Mintlify 配合使用

示例 AGENTS.md

使用 Codex

示例提示

使用 MCP 服务器增强功能

​开始使用

​将 Codex 与 Mintlify 配合使用

​示例 AGENTS.md

​使用 Codex

​示例提示

​使用 MCP 服务器增强功能

开始使用

将 Codex 与 Mintlify 配合使用

示例 AGENTS.md

使用 Codex

示例提示

使用 MCP 服务器增强功能