Prhub

#2565 docs: fold Welcome into the User Guide tab and lead with it

原始 PR 作者 QQontheMoon 合并时间 2026-08-16 05:45 文件变更 1 提交数 3 评论 1 代码增减 +37 / -32

执行摘要

Welcome 折入 User Guide 并置顶,重构文档导航

PR body 说明:Welcome 标签页只含首页和三个 getting-started 页面,却排在 Models 之后,导致读者从文档根进入后要跨过 Models 标签才能继续 Quick Start 之后的指南。改动把整条阅读路径收进同一个侧边栏,并将 User Guide 提到导航栏首位,使 /docs 首页的下一步就是侧边栏第一行。

仅改动一个 JSON 文件、无页面与 URL 变化,不值得逐行精读;建议快速浏览其结构意图,理解 Mintlify docs.json 中 tab、group、expanded 的层级约定。若后续要继续整理文档导航,可参考最近几个 docs 系列 PR 的页面分组思路,并顺手补齐 Agentic Environmentsexpanded: false

讨论亮点

review 仅由 claude[bot] 和 Zhichenzzz 参与,无实质性争议:

  • claude[bot] 总评:"Looks good — a straightforward docs navigation restructure with one minor cosmetic nit flagged inline.",并确认 JSON 结构有效、无页面丢失、无 URL 变化、无安全风险。
  • 唯一 inline 意见指向 Agentic Environments 组缺 expanded: false,与文件内所有其他深度 >=2 的组不一致,属纯外观问题;评审者明确表示 "not significant enough to block approval"。
  • 维护者 Zhichenzzz 最终 APPROVED(无附加说明),PR 合入。

实现拆解

按以下步骤拆解(仅涉及 docs/docs.json):

  1. 折叠 Welcome 标签页:在 navigation.tabs 中删除独立的 Welcome tab,把 indexgetting-started/indexgetting-started/installationgetting-started/quick-start 四页原样包裹为一个 Welcome group,并放到新 User Guide 标签页的 pages 数组首位。
  2. 重组 User Guide 内容:原有 User Guide 标签页下的所有 user-guide/* 页面被包成新的 User Guide group;Agentic Environments 组随之从 tab 直属层级降为二级分组,user-guide/cli-reference 仍保留在 tab 直属层级。
  3. 调整标签页顺序User Guide 从第 3 个 tab 提前到第 1 个,Models 顺延后移,Advanced Features 位置不变;/docs 首页仍由未改动的 index.md 提供。
  4. 配套说明:没有新增或删除任何 .md 页面,URL 均不变,git diff -M 报告零 rename;无测试、构建或 CI 配合改动。提交记录中两次 Merge branch 'main' 仅同步主干,无额外功能变更。
文件 模块 状态 重要度
docs/docs.json 文档导航 modified 4.16

关键源码片段

docs/docs.json configuration

本次 PR 唯一变更文件,集中体现导航结构重组的全部逻辑:Welcome 从独立 tab 降为 User Guide 的首个 group,User Guide 标签页移入导航栏首位。

// docs/docs.json —— navigation.tabs 核心结构(head 版本,已整理)
"navigation": {
  "tabs": [
    {
      // User Guide 现在是导航栏第一个标签页,Welcome 页组折叠为它的首个分组
      "tab": "User Guide",
      "pages": [
        {
          // 原 Welcome 标签页的四页原样保留,仅从 tab 降级为 group
          "group": "Welcome",
          "pages": [
            "index",
            "getting-started/index",
            "getting-started/installation",
            "getting-started/quick-start"
          ]
        },
        {
          "group": "User Guide",
          "pages": [
            "user-guide/index",
            "user-guide/concepts",
            "user-guide/launch-script",
            "user-guide/argument-groups",
            "user-guide/fully-async",
            "user-guide/training-backend",
            "user-guide/monitoring",
            "user-guide/dashboard",
            "user-guide/customization",
            "user-guide/generate-endpoint",
            "user-guide/agentic-rollout",
            {
              // 该组从标签页直属降为二级分组,未补 expanded: false,是唯一外观不一致点
              "group": "Agentic Environments",
              "pages": [
                "user-guide/environments",
                "user-guide/harbor",
                "user-guide/openenv",
                "user-guide/nemo-gym",
                "user-guide/verifiers"
              ]
            }
          ]
        },
        "user-guide/cli-reference"
      ]
    },
    // Models、Advanced Features 等标签页整体保持不变,仅顺序后移
    ...
  ]
}

评论区精华

Agentic Environments 二级分组缺少 expanded: false style

claude[bot] 在 docs/docs.json:67-75 指出:嵌套后的 Agentic Environments 组没有设置 expanded: false,而文件中所有其他深度 >=2 的组(DeepSeek、Qwen、GLM、Kimi、Nemotron、Gemma、Thinking Machines 等)都设置了,导致它是唯一默认预展开的二级分组。

结论:评审者确认纯外观问题,不影响链接、构建与内容,明确表示 "not significant enough to block approval";head 版本未修复该处,PR 由 Zhichenzzz APPROVED 并合入。 · 未解决,已放行

风险与影响

风险整体很低,属于文档站点静态导航配置:

  • 配置风险:docs/docs.json 是 Mintlify 导航的唯一数据源,若 JSON 结构错误会导致站点构建或导航渲染异常;review 已人工验证 JSON 有效且页面数组完整。
  • 外观不一致:Agentic Environments 在嵌套后未补 expanded: false,会以预展开状态渲染,与同层级收起的 User Guide 组不一致,对阅读有轻微视觉干扰,但不影响链接和内容可达性。
  • 兼容性:没有改动任何 index.md 或页面 URL,外部链接、书签、SEO 路径均不受影响。
  • 测试风险:PR 无自动化测试(文档配置场景下可接受),回归主要依赖 Mintlify 预览人工检查。

影响范围限于文档站导航 UX:

  • 新读者从 /docs 落地后落在首页,但激活标签页变为 User Guide,下一步操作就是侧边栏首行,阅读路径更连续,避免“跨过 Models 标签”的跳转。
  • Welcome 独立标签页消失,但其中页面以分组形式完整保留,老链接依旧可用。
  • Models 从首个标签页退居第二位,模型文档可发现性理论上略降,但 URL 和内容未变。
  • 对代码、训练、CI 等系统无任何影响,团队后续维护文档导航可沿用这套 tab 到 group 的折叠模式。
仅配置变更 侧边栏展开状态不一致

关联 Issue

未识别关联 Issue

当前没有检测到明确关联的 Issue 链接,后续同步到相关引用后会出现在这里。

完整报告

参与讨论