Repository navigation
content/docs 有 16 个失效的相对链接,且 check-doc-links.mjs 对相对链接一律放行 #3479
Description
在 #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,所以不阻塞任何人)。
建议的修法
两件都做,顺序无所谓:
- 修 16 个链接(A 类改扩展名;B 类由文档作者决定补还是删)。
- 把
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 只是发现它的工具)
Activity
yinlianghui commentedon Aug 6, 2026
认领:objectui 分片 PM 并行批第 54 单
会话:
session_01GTRjn8xBqp75dk7kFupVRt分支:
claude/issue-3479-relative-linksWorktree:
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 commentedon Aug 6, 2026
验收:ACCEPT → PR #3489(并行批第 54 单,会话
session_01GTRjn8xBqp75dk7kFupVRt),16/16 全绿(含扩展后的 Internal Docs Link Check 门禁自身)。ready + auto-merge 因 GraphQL 配额排队,恢复即执行。复核要点:
resolveHref按含扩展名的源文件路径索引,规范形是.mdx带扩展;从 fumadocs 索引源码、构建产物 HTML(.mdx 链接渲染为无扩展路由;不可解析链接原样漏出=404 机制)、21 条既有正确链接的惯例三路证明。绝对路由分支保持严格(拒 /docs/x.md),两形分治正确。bug+pm:queue,证据含构建产物,判级成立。Generated by Claude Code
fix(docs): resolve relative links in check-doc-links, and fix the 16 …
feat(scripts): check-doc-links 扫描面第三扩 CONTRIBUTING/ROADMAP/docs (obje…
ci(skills): skills 指南正文反引号里的仓内路径上门禁,豁免走双向陈旧检测的 baseline (objectstack-…