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

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

2. 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/[email protected]
       - uses: gaurav-nelson/[email protected]
   

Real-life usage samples

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

1. netdata
2. GoogleChrome/lighthouse
3. hashicorp/packer
4. prometheus-operator
5. apache/apisix

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
• Status code 429: Too many requests

Custom variables

You customize the action by using the following variables:

Sample workflow with variables

name: Check Markdown links

on: push

jobs:
  markdown-link-check:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/[email protected]
    - uses: gaurav-nelson/[email protected]
      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 hygine 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/[email protected]
    - uses: gaurav-nelson/[email protected]
      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.

1. <!-- markdown-link-check-disable --> and <!-- markdown-link-check-enable-->: 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 -->
     

2. <!-- markdown-link-check-disable-next-line --> Use this comment to disable link checking for the next line.
3. <!-- markdown-link-check-disable-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 modififed 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/[email protected]
    - uses: gaurav-nelson/[email protected]
      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/[email protected]
    - uses: gaurav-nelson/[email protected]
      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]
}

Versioning

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

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

   - uses: gaurav-nelson/[email protected]
   

2. To use a major version of the action:

   - uses: gaurav-nelson/[email protected]
   

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

   - uses: gaurav-nelson/[email protected]fb79f1f478