Prhub

#2374 docs: split FAQ out of Resources and link the blog to LMSYS

原始 PR 作者 Shi-Dong 合并时间 2026-08-12 02:11 文件变更 4 提交数 3 评论 2 代码增减 +20 / -85

执行摘要

FAQ 独立成顶级 Tab,Blog 改链 LMSYS

Issue #2361 提出 Resources tab 计划:FAQ 独立为顶级 tab;博客链接到 LMSYS(未来 LMSYS 会有 Miles tab,当前先链整站 https://www.lmsys.org/blog);Subscribe 移到 Resources 下。PR body 还说明本地 Introducing Miles 发布公告已发布在 LMSYS,且仓库内没有其他页面链接到它,故直接删除本地副本以减少重复维护。

该 PR 属于轻量文档导航调整,不必精读代码,但值得关注两点设计:一是“页面收敛为指针 + 保留原路径”的做法(FAQ 路径不变避免断链);二是用 3 个 commit 逐步收紧文案,从结构调整到元数据打磨。若团队在维护 Mintlify 文档站,可把它当作导航小改动的参考样板,后续留意 LMSYS Miles tab 上线后的链接细化。

讨论亮点

Review 中只有两条作者自评,均针对 docs/blog/index.md:

  • “Can we drop the description field?”——最终版本删除了 description 元数据。
  • 给出目标文案“Check out Miles blog posts on the LMSYS blog”,最终提交采纳为该页唯一正文。
    另一个 reviewer Zhichenzzz 直接 APPROVED,无其他争议或未解决疑问。

实现拆解

  1. 调整导航配置 docs/docs.json:将 Resources 组内 pages 由 faqblog/index 改为 blog/indexsubscribe,并在顶层新增独立 FAQ tab(pages 为 faq)。这是本次改版的核心契约,/faq 路径保持不变,已有链接不会失效。
  2. 精简 docs/blog/index.md:删除原 description 元数据、本地博文卡片(CardGroup)和 Subscribe 区块,整页收敛为一行指向 https://www.lmsys.org/blog 的链接,本地不再维护长篇发布文案。
  3. 删除 docs/blog/introducing-miles.md:67 行本地 launch 博文整体移除。PR body 说明该公告已在 LMSYS 博客发布,且仓库内没有其他页面链接到它,避免双份发布内容漂移。
  4. 新增 docs/subscribe.md:把原 Blog 页底部的订阅信息(GitHub releases、Twitter/X)迁移为独立页面,并挂载到 Resources tab 下。
  5. 验证配套:无源码或测试改动;PR 自带 Mintlify preview 手动检查清单(顶级 tab 展示、Resources 侧边栏、/blog/subscribe/faq 渲染),并确认 docs.json 解析通过(仅保留 main 分支上已存在的一个顶层 quirk)。
文件 模块 状态 重要度
docs/docs.json 文档导航 modified 4.05
docs/blog/introducing-miles.md 博客文章 removed 3.62
docs/blog/index.md 博客页 modified 2.92
docs/subscribe.md 订阅页 added 2.43

关键源码片段

docs/docs.json configuration

本次变更的核心导航配置:FAQ 升级为顶级 tab,Resources 下新增 subscribe 页,决定整个文档站 tab 与侧边栏结构。

{
  "navigation": [
    // 前面 Developer Guide、Platforms 等 tab 保持不变,此处只列本次调整涉及的 tab
    {
      "tab": "Resources",
      "groups": [
        {
          "group": "Resources",
          "pages": [
            "blog/index", // Blog 页收敛为一行指向 LMSYS 的链接
            "subscribe"   // 原 Blog 页底部的订阅信息迁移到独立页面
          ]
        }
      ]
    },
    {
      "tab": "FAQ",       // FAQ 从 Resources 拆出,成为与 Resources 平级的顶级 tab
      "groups": [
        {
          "group": "FAQ",
          "pages": [
            "faq"         // 页面路径保持 /faq 不变,旧链接不失效
          ]
        }
      ]
    }
  ]
}

评论区精华

Blog 页 description 字段去留 style

作者自评:"Can we drop the description field?",针对 blog/index.md front matter 中保留的 description 元数据。

结论:采纳:最终版本移除 description,页面仅保留 title 与一行链接。 · 已解决

Blog 指针页文案 documentation

作者自评建议文案:"Check out Miles blog posts on the LMSYS blog",替代原来更多字的表述。

结论:采纳:最终提交的一行文案即该建议。 · 已解决

风险与影响

纯文档导航变更,整体风险低。具体关注点:

  • 外部依赖:/blog 现在依赖于 www.lmsys.org/blog 的可用性;LMSYS 的 Miles tab 尚未开通,当前只能链到整个 blog,粒度不够细。
  • 404 风险:删除 introducing-miles.md 后 /blog/introducing-miles 将 404;PR 确认仓库内无其他链接引用,但外部书签或搜索引擎流量不受控。
  • 校验薄弱:导航变更只靠 Mintlify 预览手测,没有 CI 自动断言 docs.json schema 与页面存在性;且 PR 提到 main 上已有一个 pre-existing 顶层 quirk,后续改动需留意。

用户侧:文档站导航更清晰,FAQ 更容易被发现,Resources 收纳 Blog 与 Subscribe,博客入口改为外部 LMSYS,发布信息实现单一来源。系统侧:仅 docs 资源变化,不影响运行时、构建与测试。团队侧:LMSYS 上线 Miles tab 后只需再次修改 docs/blog/index.md 中的链接即可;删除本地博文后免去双份发布文案的维护成本。

外部链接依赖 删除页面可能 404 无自动化导航校验

关联 Issue

#2361 [Docs] Resources tab

完整报告

参与讨论