《Codex 完整教程》站点维护指南
本指南说明如何维护教程内容、更新导航并发布网站。站点使用 Mintlify 构建，内容通过 Git 推送后自动部署。站点信息
推送到
main 分支后，Mintlify 会自动构建并发布。通常等待 1–2 分钟即可看到更新。
目录结构
.md 文件，首页使用 index.mdx；docs.json 中的导航路径不写文件扩展名。
页面格式
每个新页面都应包含title 和 description：
更新页面和导航
-
在对应章节目录中创建或编辑
.md/.mdx页面。 -
在
docs.json的navigation中加入页面路径，否则页面不会出现在侧边栏中。 -
导航路径使用根路径形式且不带扩展名，例如：
-
页面之间的内部链接也使用根路径、不带扩展名，例如：
docs.json 和相关内部链接。
本地检查
在文档仓库根目录执行：mint broken-links 检查站内链接，mint validate 检查配置和页面格式。旧目录 旧/ 中可能保留历史断链；如果检查报告只涉及该目录，先确认没有影响新增 Codex 页面。
需要预览时运行：
Ctrl+C。
提交和发布
确认检查通过后执行： 推送时需要使用 7897 端口；提交前确认当前 Git 远端或代理配置没有绕过该端口。故障排查
- 侧边栏没有页面：检查页面是否已加入
docs.json的navigation，并确认路径与文件名完全一致。 - 页面返回 404：检查路径大小写、中文字符和扩展名；导航和内部链接都不要写
.md或.mdx。 - 推送后没有更新：确认推送目标为
MAX-API-Next/docs的main分支，并在 Mintlify 控制台查看部署状态。 - 本地预览启动失败：先运行
mint update更新 CLI，再重新执行mint dev。 - 构建出现旧内容断链：优先确认报告中的路径是否属于
旧/；修复新 Codex 页面产生的错误后再处理历史内容。
维护原则
- 章节顺序遵循“认识 → 上手 → 入口 → 工作流 → 安全 → 定制 → 扩展 → 工程化 → 实战 → 查阅”。
- 示例应可运行，涉及权限、网络、密钥和 Git 的操作要明确风险及回滚方式。
- 不直接修改
旧/中的历史页面，除非任务明确要求迁移或修复。 - 每次发布尽量只包含一个主题的改动，便于审查、回滚和定位问题。