content/docs 有 16 个失效的相对链接,且 check-doc-links.mjs 对相对链接一律放行

[yinlianghui]

在 #3449(PR #3477)把 Lychee 扫描范围修到 content/docs/** 之后,离线跑出来的副产物:content/docs 里有 16 个失效的相对链接目标(33 处引用),一直没人管。

两件事,一因一果

1. 门禁洞(因)

scripts/check-doc-links.mjs 的 routeExists():

if (!cleanHref || !cleanHref.startsWith(DOCS_ROUTE_PREFIX)) {
  return true;
}

只要 href 不是以 /docs 开头就直接判过。也就是说 docs-links.yml 这个 PR 门禁只校验站内绝对路由,../plugins/plugin-view.md 这类相对链接一律放行 —— 它们至今由任何门禁都不检查(Lychee 在 #3449 之前也看不到 content/docs)。

2. 累积出来的失效链接(果)

lychee 0.24.2 --offline 实测(命令见文末),16 个失效目标:

A. 扩展名写错 —— 链接写 .md,文件其实是 .mdx(13 个)

content/docs/plugins/ 下这些文件都存在,但都是 .mdx:

plugin-calendar.md   plugin-charts.md    plugin-chatbot.md   plugin-dashboard.md
plugin-editor.md     plugin-form.md      plugin-gantt.md     plugin-grid.md
plugin-kanban.md     plugin-map.md       plugin-markdown.md  plugin-timeline.md
plugin-view.md

这在站点上也是坏的:fumadocs 的路由不带扩展名,/docs/plugins/plugin-view.md 是 404。

B. 目标根本不存在(3 个)

目标	引用处
content/docs/concepts/lazy-loading	plugins/plugin-charts.mdx:281、plugin-editor.mdx:154、plugin-kanban.mdx:365、plugin-markdown.mdx:362
content/docs/guide/lazy-loading.md	guide/plugins.md:515
content/docs/guide/examples/server	guide/index.md:12

content/docs/ 下没有 concepts/ 目录,全仓库也找不到任何 lazy-loading 文档(find content/docs -iname '*lazy*' 为空)。所以 A 类是改扩展名,B 类要么补文档、要么删链接 —— 需要写文档的人判断,不是机械替换。

影响

• 站点读者点这些链接会 404。
• check-links.yml(Lychee)扫的是 docs/**(15 个文件),不是站点文档 content/docs/**(183 个文件) #3449 修好后,check-links.yml 的每周 cron 会持续把它们报出来(该 workflow 只报告、不拦 PR,所以不阻塞任何人)。

建议的修法

两件都做,顺序无所谓:

1. 修 16 个链接(A 类改扩展名;B 类由文档作者决定补还是删)。
2. 把 check-doc-links.mjs 扩到相对链接 —— 它已经在遍历 content/docs 的每个文件,知道每个 href 所在的文件路径,解析相对路径是几行的事;而且它是无网络的 PR 门禁,天然适合管仓库内链接。管住了以后这类缺陷就不会再攒起来。

注:PR #3477 特意没有用 --fallback-extensions md,mdx 把 A 类盖掉 —— 那样错误数从 33 降到 6,但降下去的正是真缺陷。宽容的消费端把生产端的错误藏起来,是这个仓库明确要避免的方向。

复现

lychee --offline --no-progress --config lychee.toml \
  'content/docs/**/*.md' 'content/docs/**/*.mdx'
# (需要 PR #3477 的 lychee.toml —— 否则会先被 297 个站内绝对路由的硬错误淹掉)

Blocked-by: none(可以独立修;#3477 只是发现它的工具)

[yinlianghui]

认领:objectui 分片 PM 并行批第 54 单
会话:session_01GTRjn8xBqp75dk7kFupVRt
分支:claude/issue-3479-relative-links
Worktree:objectui-issue-3479
文件面:scripts/check-doc-links.mjs(扩展到相对链接校验)+ content/docs/** 的 16 处断链修复 + checker 自测 + 必要的门禁自证。⛔ 不动 .github/workflows(门禁已由 docs-links.yml 承载)。
B 类三个不存在目标的裁量:先查 git 历史;lazy-loading 文档若从未存在,改指真实存在的相邻文档或删句并说明,⛔ 不新写文档(超范围);逐处在 PR 里记理由。
与同批各单互不相交(README.md 归 55 单,勿碰)。

---

Generated by Claude Code

[yinlianghui]

验收:ACCEPT → PR #3489(并行批第 54 单,会话 session_01GTRjn8xBqp75dk7kFupVRt),16/16 全绿(含扩展后的 Internal Docs Link Check 门禁自身)。ready + auto-merge 因 GraphQL 配额排队,恢复即执行。

复核要点:

1. 归因更正是本单的承重发现:issue 断言「fumadocs 路由无扩展名所以 .md 是 404」对相对链接不成立——resolveHref 按含扩展名的源文件路径索引,规范形是 .mdx 带扩展;从 fumadocs 索引源码、构建产物 HTML(.mdx 链接渲染为无扩展路由;不可解析链接原样漏出=404 机制)、21 条既有正确链接的惯例三路证明。绝对路由分支保持严格(拒 /docs/x.md),两形分治正确。
2. 代码剥离是必需非润色:不剥则 34/17 与 issue 的 33/16 对不上——计数吻合本身成了「剥离正确」的证据;空格填充保行号真实。
3. B 类三处逐一以 git 史裁量(删块/删自指 bullet/深链重定向),零新写文档,理由齐备;反向验证 6/16 按预测(并如实声明 repo-integration 用例是内容证据非守卫)。
4. 设计问题(是否拒绝无扩展相对形)按裁定保守接受并把脆弱性写进脚本头——认同不趁手收紧(防撞在飞 PR);后续收紧锚在 content/docs 有 18 条链接在站上是 404,但 check-doc-links 按设计放行(1 条相对链接跑出 docs collection + 17 条 /spec /protocol /api /examples 绝对链接) #3490 一并考虑。
5. content/docs 有 18 条链接在站上是 404,但 check-doc-links 按设计放行(1 条相对链接跑出 docs collection + 17 条 /spec /protocol /api /examples 绝对链接) #3490(18 条两个检查器结构上都看不见的站点 404——文件系统能解析≠路由存在)已分诊 bug+pm:queue,证据含构建产物,判级成立。

---

Generated by Claude Code