REF-001 链接断裂

概述

验证 Markdown 中的相对链接(形如 [text](./file.md))指向实际存在的文件。链接目标不存在时,会报告为 error。锚点片段(#section)不参与链接目标判定,其有效性由 REF-005 锚点负责。

为什么需要

在 Markdown 运维中,因文件重命名、删除、移动导致的链接损坏是最常见的劣化形式。AI 生成时也可能混入指向不存在文件的链接。即便链接断裂,markdownlint 与 CI 仍会通过,因此机械化检测是必要的。

选项

字段	类型	必填	说明
`exclude`	string[]	—	从链接目标验证中排除的路径 glob 数组
`siteRouter`	object	—	将 SSG 的 routed URL（如 `/docs/x/`）解析为实际文件的配置

省略全部选项也可工作。exclude 用于像外部文档或生成物那样不在 include 范围内、但被有意引用的文件。

`siteRouter` — SSG 的 routed URL 支持

默认情况下 REF-001 把 ./file.md 这类相对链接当作 file system 路径解析。但 Astro Starlight 等 SSG 生成的 routed URL（/docs/x/ 或 /ja/docs/x/）作为 file path 并不存在，因此不指定 siteRouter 就会被判定为 broken link。

子字段	类型	必填	说明
`preset`	string	—	已知的 SSG 预设。目前仅支持 `"starlight"`
`contentDir`	string	✓	内容目录（如 `"packages/site/src/content/docs"`）
`defaultLocale`	string	—	默认 locale。Starlight 无前缀的 root locale 指定为 `"root"`
`locales`	string[]	—	支持的 locale 列表（如 `["root", "ja", "ko", "zh"]`）
`urlPrefix`	string	—	(不使用 preset 的通用配置) 从 URL 中剥离的前缀
`indexFile`	string	—	最先尝试的 index 文件名（默认: `"index.md"`）

Starlight (i18n) 示例:

{
  "rule": "ref001",
  "options": {
    "siteRouter": {
      "preset": "starlight",
      "contentDir": "packages/site/src/content/docs",
      "defaultLocale": "root",
      "locales": ["root", "ja", "ko", "zh"]
    }
  }
}

/docs/get-started/ 解析为 <contentDir>/docs/get-started/index.md 或 <contentDir>/docs/get-started.md。/ja/docs/get-started/ 解析为 <contentDir>/ja/docs/get-started/index.md。

通用配置（无 preset）示例:

{
  "rule": "ref001",
  "options": {
    "siteRouter": {
      "contentDir": "src/pages",
      "urlPrefix": "/wiki",
      "indexFile": "README.md"
    }
  }
}

/wiki/some-page/ 解析为 src/pages/some-page/README.md。

违例

详见 [架构](./architecture.md)。

./architecture.md 不存在时,判定为违例。

docs/overview.md
  line 1  error  Link target "./architecture.md" does not exist  REF-001

修正后

详见 [架构](./architecture.md)。

创建链接目标文件 architecture.md,或将链接修正为正确的路径。

配置示例

{
  "rule": "ref001",
  "options": {
    "exclude": ["generated/**/*.md"]
  }
}

REF-001 链接断裂

概述

为什么需要

选项

siteRouter — SSG 的 routed URL 支持

违例

修正后

配置示例

相关规则

`siteRouter` — SSG 的 routed URL 支持