GitHub Action - Markdown 链接检查工具使用教程

1、项目介绍

github-action-markdown-link-check 是一个用于检查 Markdown 文件中链接有效性的 GitHub Action。它可以帮助开发者在每次代码推送或定时任务中自动检查项目中的 Markdown 文件，确保所有链接都是有效的，避免因链接失效导致的文档问题。

该项目由 Gaurav Nelson 开发，基于 tcort/markdown-link-check 工具，提供了更便捷的集成方式，适用于任何使用 GitHub Actions 的项目。

2、项目快速启动

2.1 创建 GitHub Action 配置文件

在你的 GitHub 仓库中，创建一个新的 .github/workflows/markdown-link-check.yml 文件，并复制以下内容：

name: 检查 Markdown 链接

on:
  push:
    branches:
      - master
  schedule:
    - cron: "0 9 * * *"  # 每天早上 9 点运行

jobs:
  markdown-link-check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@master
      - uses: gaurav-nelson/github-action-markdown-link-check@v1
        with:
          use-quiet-mode: 'yes'
          use-verbose-mode: 'yes'
          config-file: 'mlc_config.json'
          folder-path: 'docs/markdown_files'

2.2 配置文件说明

• use-quiet-mode: 设置为 yes 时，仅在输出中显示错误信息。
• use-verbose-mode: 设置为 yes 时，显示详细的 HTTP 状态信息。
• config-file: 指定自定义配置文件的路径，用于进一步配置链接检查行为。
• folder-path: 指定需要检查的 Markdown 文件所在的目录。

2.3 自定义配置文件

你可以在项目根目录下创建一个 mlc_config.json 文件，用于自定义链接检查的行为。例如：

{
  "retryOn429": true,
  "retry-after": 5,
  "retryCount": 3,
  "fallbackRetryDelay": 10,
  "aliveStatusCodes": [429, 200],
  "httpHeaders": [
    {
      "urls": ["https://github.com/", "https://guides.github.com/"],
      "headers": {
        "Accept-Encoding": "zstd, br, gzip, deflate"
      }
    }
  ]
}

3、应用案例和最佳实践

3.1 定期检查链接

通过设置 schedule 字段，你可以让 GitHub Action 定期检查链接，例如每天早上 9 点运行一次。这对于维护文档的时效性非常有帮助。

3.2 检查特定文件或目录

通过 folder-path 和 file-path 参数，你可以指定需要检查的文件或目录，避免检查不必要的文件，提高效率。

3.3 处理 429 状态码

当遇到 429 状态码（请求过多）时，可以通过配置文件中的 retryOn429、retry-after 等参数进行重试，确保链接检查的完整性。

4、典型生态项目

以下是一些使用 github-action-markdown-link-check 的典型项目：

• Netdata: 一个开源的实时性能监控工具，使用该 Action 定期检查文档中的链接。
• GoogleChrome/lighthouse: Google 的 Lighthouse 项目，用于网页性能测试，使用该 Action 确保文档链接的有效性。
• Tendermint/tendermint: 一个区块链共识引擎，使用该 Action 维护文档的链接质量。
• Pyroscope-io/pyroscope: 一个开源的持续性能分析平台，使用该 Action 定期检查文档链接。

这些项目通过集成 github-action-markdown-link-check，确保了文档的时效性和准确性，提升了用户体验。