执行摘要
本次 PR 修复了 Miles 文档站的系统性 SEO 缺口：5 个 CI 文档页与 advanced/on-policy-distillation 因不在 docs.json 导航树中而从未被 Mintlify 索引，首页与 blog 缺少 meta description。作者将 6 页全部纳入导航、补齐页面 description、删除重复 H1，并把 docs.json 从 v1 schema 对齐到 v2（移除站点级 canonical 与非法顶层 url，新增 seo.organization 和顶层 description），可索引页面从 83 增至 89。纯文档/配置变更，无运行时影响，已通过 mint validate 与 mint broken-links 验证。
功能与动机
Mintlify 的 seo.indexing 默认 navigable：页面缺失于 docs.json 导航树就不会进 sitemap 和搜索结果，即使文件存在且其他页面链接它。五个 docs/ci/ 页面与 advanced/on-policy-distillation 都处于该状态——live sitemap 携带 83 个 URL，6 个页面均不在其中；on-policy-distillation 甚至被 advanced/index 的 Card 链接，人类可达但爬虫不可见。同时首页和 blog/index 完全没有 meta description，搜索结果与社交卡片都没有描述文案。docs.json 还长期以 v1 schema.json 声明 v2 格式，使无效的顶层 url 键一直未被发现。
实现拆解
- 导航与索引修复：在
docs/docs.json 的 Developer Guide 分组下新增 CI 子组，纳入 ci/contributor-guide、ci/00-stage、ci/01-label、ci/02-docker-build、ci/03-metric-history-gate 五个页面；在 Advanced Features 的 Performance 分组中加入 advanced/on-policy-distillation。同步删除这些页面中与 frontmatter title 重复的正文 H1，并为 on-policy-distillation 首次补上 frontmatter 的 title 与 description。
- 元数据补全：给
docs/index.md 与 docs/blog/index.md 增加顶层 description；重写 docs/developer/debug.md（原为“Useful tips for debugging.”）与 docs/models/gpt-oss/gpt-oss.md 的单薄描述；把 docs/ci/03-metric-history-gate.md、docs/ci/contributor-guide.md 等超过约 160 字符的 description 收紧到 SERP 安全长度。
- docs.json schema 对齐：
$schema 从 v1 schema.json 指向 v2 docs.json；删除站点级 canonical（当前被 per-page canonical 覆盖，属潜在隐患）；删除顶层非法的 url 键，移入 seo.organization 块并补充 name 与 sameAs，输出 JSON-LD Organization 数据；新增顶层 description 供 SEO/AEO 使用。
- 站内链接化与维护规范：把正文中按文件路径书写的引用改为站内链接，涉及
docs/developer/contributor-guide.md、docs/developer/versions.md、docs/ci/00-stage.md；在 docs/README.md 中明确 description 必填、控制在 160 字符内、缺失导航条目即不被索引的规范。
- 验证：
mint validate（严格模式）与 mint broken-links 从 docs/ 运行均干净，导航覆盖核对为 89 文件 ↔ 89 条目、无孤儿页。
docs/docs.json
文档站唯一根配置：升级 $schema 到 v2、新增顶层 description、删除站点级 canonical、把 url 移入 seo.organization，并在导航树中补入 OPD 与 CI 组 6 个页面，是整个 SEO 修复的核心。
{
// 从 v1 schema.json 升级到 v2 docs.json：此前文件已是 v2 格式却声明 v1，
// 导致顶层无效键 url 从未被校验发现
"$schema": "https://mintlify.com/docs.json",
"name": "Miles",
// 顶层 description：Mintlify 会把它用于 SEO 与 AEO，此前首页完全没有它
"description": "Miles is an open-source reinforcement learning framework for large-scale LLM post-training, pairing SGLang rollout with Megatron-LM training at trillion-parameter scale.",
"seo": {
// 删除站点级 canonical：Mintlify 已为每页生成正确的 per-page canonical，
// 旧配置是被覆盖的“哑配置”，但若优先级变化将变成全站指向 /docs 的隐患
"metatags": {
"og:site_name": "Miles Documentation"
},
// url 从顶层移入 organization：在 v2 schema 中顶层 url 不是合法键，
// 这里它有了合法位置，并输出 JSON-LD Organization 结构化数据
"organization": {
"name": "RadixArk",
"url": "https://www.radixark.com",
"sameAs": ["https://github.com/radixark"]
}
},
// 导航即索引：Mintlify 的 seo.indexing 默认 navigable，
// 不在 navigation 里的页面不会进 sitemap，也不会被搜索到。
// 以下截取与本次修复相关的导航片段
"navigation": {
"tabs": [
{
"tab": "Developer Guide",
"groups": [
{
"group": "Developer Guide",
"root": "developer/index",
"pages": [
"developer/experimental-features",
{
// 五个 CI 文档页整体纳入导航，它们与 advanced/on-policy-distillation
// 一起使可索引页面数从 83 增至 89
"group": "CI",
"pages": [
"ci/contributor-guide",
"ci/00-stage",
"ci/01-label",
"ci/02-docker-build",
"ci/03-metric-history-gate"
],
"expanded": false
}
]
}
]
}
]
}
}
评论区精华
该 PR 没有 review 评论，Zhichenzzz 直接 APPROVED。实质决策都记录在 PR body 中：作者对比 live 页面 <head> 后发现 Mintlify 已生成 per-page OG 卡，因此放弃自制全站 og:image——静态 logo 反而会替代更好的现状；同时主动搁置 font、background、logo.width 死配置与主色 #d55816 对比度 4.01:1 未达 WCAG AA 4.5:1 的问题，明确说明这两者会改变站点外观，超出本次 SEO 范围，值得单独处理。
风险与影响
docs.json 是 Mintlify 站点配置的单一根入口：导航结构或 schema 写错可能导致页面从侧边栏消失或构建失败，本次通过 mint validate 严格模式加 mint broken-links 双验证、89/89 覆盖核对，风险已收敛。删除站点级 canonical 依赖“Mintlify 每页生成正确 canonical 并优先”的当前行为，若平台未来改变优先级，可能造成 canonical 指向缺失，需在后续上线检查中关注 <link rel="canonical">。url 移入 seo.organization 依赖 v2 schema 对该块的支持，本地验证已通过，但 JSON-LD 实际渲染属于平台的生成行为，实测风险低。作者提到的 font、background、logo.width 死配置与主色对比度问题仍保留，属于后续站点质量问题。本次不触碰任何代码路径，不影响训练、推理等运行时功能。影响面仅限 docs/ 目录 15 个文件；对用户而言，CI 文档和 OPD 文档首次可被搜索引擎检索，首页与 blog 在搜索结果和社交卡片上首次拥有描述文案；对团队而言，docs/README.md 的新规范降低了未来 SEO 回归概率。
关联脉络
本 PR 与多条历史维护线衔接：PR 2376 重写开发者指南并调整 docs/docs.json 导航，本次在其基础上把 CI 文档挂到 Developer Guide 下；PR 2303 新增 docs/ci/03-metric-history-gate.md 但当时未进导航，本次补入索引，属于遗留欠账修正；PR 2363 同步维护 docs/ci/02-docker-build.md，本次把该页正式纳入导航树；PR 2391 同样通过 docs.json 调整导航把新模型页纳入索引，与本 PR 同属“导航与索引同步”维护线。整体看，Miles 文档站正在持续收口导航覆盖与元数据质量，把“页面存在但不可索引”的历史欠账逐项清零。
参与讨论