使用 Codex 编写文档
通过项目说明和 MCP 配置 OpenAI Codex CLI，以编写遵循你的样式指南和 MDX 标准的 Mintlify 文档。
使用 OpenAI 的 Codex CLI 在终端中编写和维护 Mintlify 文档。AGENTS.md 中的项目说明可为 Codex 提供关于你的文档标准、组件和样式指南的持久 context。
前置条件：
- 一个可访问 Codex 的 OpenAI 账户
设置：
- 安装 Codex CLI：
npm install -g @openai/codex- 进入你的文档目录。
- （可选）将下面的
AGENTS.md文件添加到你的项目中。 - 运行
codex启动会话。
有关安装替代方案和身份验证选项，请参阅 Codex CLI 文档。
Codex 会在开始工作之前读取仓库中的 AGENTS.md 文件，以了解项目特定的规则和约定。你可以在文档仓库的根目录中放置一个 AGENTS.md 文件，为 Codex 提供有关 Mintlify 组件、写作标准以及你如何组织文档结构的 context。
Codex 会在多个层级发现 AGENTS.md 文件：
- 全局说明位于
~/.codex/AGENTS.md，适用于你的所有项目。 - 项目说明位于你的仓库根目录（或任何子目录），适用于该范围内的工作。
Codex 会将这些文件从根目录到当前目录依次拼接，因此项目级说明会扩展或覆盖全局说明。
在你的文档仓库根目录创建 AGENTS.md 并提交，让所有贡献者都能受益于相同的 context。完整详情请参阅 Codex 文档中的 AGENTS.md。
此文件为 Codex 提供有关 Mintlify 组件和技术写作标准的 context。
根据你的文档进行自定义：
- 写作标准：更新语言规范以符合你的风格指南。
- 组件模式：添加项目特定的组件，或修改现有示例。
- 代码示例：将通用示例替换为与你的产品相关的真实 API 调用与响应。
- 风格与语气偏好：调整术语、格式和其他规则。
将其保存为文档仓库根目录中的 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完成 AGENTS.md 的配置后，当你在文档仓库中启动会话时，Codex 会自动读取该文件。
撰写新对象：
在 guides/authentication.mdx 创建一个新页面，说明如何通过我们的 API 进行身份验证。包含 JavaScript 和 Python 的代码示例。改进现有对象：
审查 docs/quickstart.mdx 并提出改进清晰度的建议。重点让步骤更易于理解，并确保正确使用组件。更新导航：
我在 guides/webhooks.mdx 添加了一个新页面。请将其添加到 docs.json 中 Guides 部分的 guides/authentication 之后。保持一致性：
检查此新页面是否符合 AGENTS.md 中的写作标准，并标记出任何问题。将 Mintlify MCP 服务器连接到 Codex，使其在帮助你写作时可以搜索 Mintlify 文档。连接 MCP 服务器后，Codex 可以查阅组件用法和配置选项，无需离开终端。
将 MCP 服务器添加到位于 ~/.codex/config.toml 的全局 Codex 配置中。如果该文件不存在，请先创建：
[mcp_servers.mintlify]
url = "https://mintlify.com/docs/mcp"如需连接到你自己文档站点的 MCP 服务器，请将 URL 替换为你站点的 MCP 端点：
[mcp_servers.my-docs]
url = "https://your-docs.mintlify.site/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。