mkdocs Validation 链接检查插件¶

目的：配置 mkdocs 链接验证插件关联：[B1-2]

1. 插件选择¶

3 个候选：

插件	优点	缺点
`mkdocs-validate-links`	主动检查	速度慢
`mkdocs-htmlproofer-plugin`	详细	复杂
`mkdocs-minify-plugin`	简单	链接检查弱

2. 完整配置¶

# mkdocs.yml
plugins:
  - search
  - validate-links:    # 主动检查
      enabled: !ENV CI  # CI 时开
      ignore:
        - ../../docs/.*  # 仓库根 docs 路径
        - https://github.com/.*#L\d+  # GitHub 行号 anchor

3 配置项： - enabled: !ENV CI —— 本地关、CI 开 - ignore —— 豁免列表 - 速度 / 准确度 tradeoff

3. 3 步集成¶

3.1 Step 1: 安装¶

pip install mkdocs-validate-links
# 或
poetry add mkdocs-validate-links

1 行。

3.2 Step 2: 配置 mkdocs.yml¶

plugins:
  - validate-links:
      enabled: !ENV CI
      ignore:
        - '.*\.md#.*'  # 忽略所有 anchor
        - 'https://github.com/.*'

配置。

3.3 Step 3: CI 集成¶

# .github/workflows/docs.yml
- run: mkdocs build --strict

strict 模式。

4. 5 个 ignore 模式¶

ignore:
  # 1. 跨仓库链接
  - 'https://github.com/.*'

  # 2. 跨文件 anchor
  - '.*\.md#.*'

  # 3. 仓库根路径
  - '\.\./\.\./.*'

  # 4. 外部 API
  - 'https://api\..*'

  # 5. 内部工具
  - 'claude-code-action://.*'

5 模式。

5. 5 个最佳实践¶

CI 才开 —— 本地开发慢
豁免跨仓库 —— GitHub 等
豁免 anchor —— 容易变
strict mode —— build 失败 = 有错
看 report —— 详细错误

6. 总结¶

mkdocs 链接验证 = CI 时开 + 豁免 + strict。

核心： - mkdocs-validate-links 插件 - !ENV CI 条件 - 5 豁免模式

下一步： - 看 B1-3 mkdocstrings TypeScript - 配 GitHub Actions