🔗

GitHub ActionでMarkdownのリンクを検査する

2021/09/28に公開

GitHub

GitHub Actions

tech

Markdown link check

これはMarkdownのテキストからLinkを抽出して、それが200 OKを返すかチェックしてくれます。

npm install --save-dev markdown-link-check

でプロジェクト毎にインストールして使うか、システムにインストールするときは-gでインストールします。

markdown-link-check ./README.md

のように引数で取ったファイルを検査してくれます：

$ markdown-link-check README.md

FILE: README.md
[✓] https://github.com/stepcode/stepcode
[✖] https://crates.io/crates/espr
[✓] https://img.shields.io/crates/v/espr.svg
[✓] https://docs.rs/espr
[✓] https://docs.rs/espr/badge.svg

...

32 links checked.

ERROR: 3 dead links found!
[✖] https://crates.io/crates/espr → Status: 404
[✖] https://crates.io/crates/ruststep → Status: 404
[✖] https://crates.io/crates/ruststep-derive → Status: 404

これはruststep/README.mdに対する結果になっています。Rustのレジストリcrates.ioはHTTPヘッダを指定しないと404を返すのでmarkdown-link-checkの設定ファイルを書く必要があります：

{
  "httpHeaders": [
    {
      "urls": ["https://crates.io/crates"],
      "headers": {
        "Accept": "text/html"
      }
    }
  ]
}

設定の詳細はconfig-file-formatを見てください。例えば特定のURLだけ除く事も出来ます。

GitHub Actionsの設定

これをGitHub Actionsとして提供してくれるのがこれです。これを使うには以下のYAMLを .github/workflows 以下に置きます：

.github/workflows/doc.yaml

name: doc

on:
  push:
    branches:
      - master
  pull_request: {}

jobs:
  markdown-link-check:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@master
    - uses: gaurav-nelson/github-action-markdown-link-check@v1
      with:
        config-file: 'markdown-link-check.json'

with:に指定できるオプションはCustom variablesに詳細があります。config-fileはmarkdown-link-checkの為の設定ファイル()で、デフォルトでmlc_config.jsonですがこれをリポジトリに置くと何のファイルか分からないので別名を指定しています。

GitHub Actionsは.github/workflows以下に存在しているYAMLファイル毎にWorkflowを作ります。ワークフロー単位でonが指定できるので、例えばmasterでのみ実行して欲しい時は次のようにできます：

on:
  push:
    branches:
      - master

GitHubで編集を提案

Markdown link check

GitHub Actionsの設定

Discussion