Awesome

<table> <tr> <td> <h3> 🚨 Update (May 2024) </h3> <p>I have developed a new tool called <a href="https://github.com/UmbrellaDocs/linkspector">Linkspector</a>, which offers improved functionality and reduced false positives. I recommend using Linkspector for your needs, which is now the preferred and supported option.</p> <h1>Try <a href="https://github.com/UmbrellaDocs/action-linkspector">GitHub action Linkspector</a>!</h1> </td> </tr> </table>

GitHub Action - Markdown link check 🔗✔️

This GitHub action checks all Markdown files in your repository for broken links. (Uses tcort/markdown-link-check)

How to use

Create a new file in your repository .github/workflows/action.yml.

Copy-paste the following workflow in your action.yml file:

name: Check Markdown links

on: push

jobs:
  markdown-link-check:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@master
    - uses: gaurav-nelson/github-action-markdown-link-check@v1

Real-life usage samples

Following is a list of some of the repositories which are using GitHub Action - Markdown link check.

If you are using this on production, consider buying me a coffee ☕.

Configuration

Custom variables
Scheduled runs
Disable check for some links
Check only modified files in a pull request
Check multiple directories and files
Status code 429: Too many requests
GitHub links failure fix

Custom variables

You customize the action by using the following variables:

Variable	Description	Default value
`use-quiet-mode`	Specify `yes` to only show errors in output.	`no`
`use-verbose-mode`	Specify `yes` to show detailed HTTP status for checked links.	`no`
`config-file`	Specify a custom configuration file for markdown-link-check. You can use it to remove false-positives by specifying replacement patterns and ignore patterns. The filename is interpreted relative to the repository root.	`mlc_config.json`
`folder-path`	By default the `github-action-markdown-link-check` action checks for all markdown files in your repository. Use this option to limit checks to only specific folders. Use comma separated values for checking multiple folders.	`.`
`max-depth`	Specify how many levels deep you want to check in the directory structure. The default value is `-1` which means check all levels.	`-1`
`check-modified-files-only`	Use this variable to only check modified markdown files instead of checking all markdown files. The action uses `git` to find modified markdown files. Only use this variable when you run the action to check pull requests.	`no`
`base-branch`	Use this variable to specify the branch to compare when finding modified markdown files.	`master`
`file-extension`	By default the `github-action-markdown-link-check` action checks files in your repository with the `.md` extension. Use this option to specify a different file extension such as `.markdown` or `.mdx`.	`.md`
`file-path`	Specify additional files (with complete path and extension) you want to check. Use comma separated values for checking multiple files. See Check multiple directories and files section for usage.	-

Sample workflow with variables

name: Check Markdown links

on: push

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'
        max-depth: 2

Scheduled runs

In addition to checking links on every push, or pull requests, its also a good hygiene to check for broken links regularly as well. See Workflow syntax for GitHub Actions - on.schedule for more details.

Sample workflow with scheduled job

name: Check Markdown links

on:
  push:
    branches:
    - master
  schedule:
  # Run everyday at 9:00 AM (See https://pubs.opengroup.org/onlinepubs/9699919799/utilities/crontab.html#tag_20_25_07)
  - cron: "0 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'

Disable check for some links

You can include the following HTML comments into your markdown files to disable checking for certain links in a markdown document.

 and : Use these to disable links for all links appearing between these comments.

Example:

<!-- markdown-link-check-disable -->
## Section

Disbale link checking in this section. Ignore this [Bad Link](https://exampleexample.cox)
<!-- markdown-link-check-enable -->

 Use this comment to disable link checking for the next line.
 Use this comment to disable link checking for the current line.

Check only modified files in a pull request

Use the following workflow to only check links in modified markdown files in a pull request.

When you use this variable, the action finds modified files between two commits:

latest commit in you PR
latest commit in the master branch. If you are suing a different branch to merge PRs, specify the branch using base-branch.

NOTE: We can also use GitHub API to get all modified files in a PR, but that would require tokens and stuff, create an issue or PR if you need that.

on: [pull_request]
name: Check links for modified files
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'
        check-modified-files-only: 'yes'

Check multiple directories and files

on: [pull_request]
name: Check links for modified files
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'
        folder-path: 'md/dir1, md/dir2'
        file-path: './README.md, ./LICENSE, ./md/file4.markdown'

Too many requests

Use retryOn429, retry-after, retryCount, and fallbackRetryDelay in your custom configuration file. See https://github.com/tcort/markdown-link-check#config-file-format for details.

Or mark 429 status code as alive:

{
  "aliveStatusCodes": [429, 200]
}

GitHub links failure fix

Use the following httpHeaders in your custom configuration file to fix GitHub links failure.

{
  "httpHeaders": [
    {
      "urls": ["https://github.com/", "https://guides.github.com/", "https://help.github.com/", "https://docs.github.com/"],
      "headers": {
        "Accept-Encoding": "zstd, br, gzip, deflate"
      }
    }
  ]
}

Example Usage

Consider a workflow file that checks for the status of hyperlinks on push to the master branch,

name: Check .md links

on:
  push: [master]

jobs:
  markdown-link-check:
    runs-on: ubuntu-latest
    # check out the latest version of the code
    steps:
    - uses: actions/checkout@v3

    # Checks the status of hyperlinks in .md files in verbose mode
    - name: Check links
      uses: gaurav-nelson/github-action-markdown-link-check@v1
      with:
        use-verbose-mode: 'yes'

A file test.md exists, containing

On running the workflow described above, the output shown below is obtained

Versioning

GitHub Action - Markdown link check follows the GitHub recommended versioning strategy.

To use a specific released version of the action (Releases):

- uses: gaurav-nelson/github-action-markdown-link-check@1.0.1

To use a major version of the action:

- uses: gaurav-nelson/github-action-markdown-link-check@v1

You can also specify a specific commit SHA as an action version:

- uses: gaurav-nelson/github-action-markdown-link-check@44a942b2f7ed0dc101d556f281e906fb79f1f478