# PR #2400 完整报告 - 仓库：`radixark/miles` - 标题：docs: fix SEO gaps across the docs site - 合并时间：2026-08-12 08:00 - 原文链接：http://prhub.com.cn/radixark/miles/pull/2400 --- # 执行摘要 本次 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` 键一直未被发现。 ## 实现拆解 1. **导航与索引修复**：在 `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。 2. **元数据补全**：给 `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 安全长度。 3. **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 使用。 4. **站内链接化与维护规范**：把正文中按文件路径书写的引用改为站内链接，涉及 `docs/developer/contributor-guide.md`、`docs/developer/versions.md`、`docs/ci/00-stage.md`；在 `docs/README.md` 中明确 description 必填、控制在 160 字符内、缺失导航条目即不被索引的规范。 5. **验证**：`mint validate`（严格模式）与 `mint broken-links` 从 `docs/` 运行均干净，导航覆盖核对为 89 文件 ↔ 89 条目、无孤儿页。 ### `docs/docs.json` 文档站唯一根配置：升级 $schema 到 v2、新增顶层 description、删除站点级 canonical、把 url 移入 seo.organization，并在导航树中补入 OPD 与 CI 组 6 个页面，是整个 SEO 修复的核心。 ```jsonc { // 从 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 页面 `` 后发现 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 指向缺失，需在后续上线检查中关注 ``。`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 文档站正在持续收口导航覆盖与元数据质量，把“页面存在但不可索引”的历史欠账逐项清零。