GitHub Action: My Markdown Link Checker

This is a GitHub Action to check Markdown files for broken links. This Action uses the markdown-link-check library and fd command-line utility.

Below is a basic example of how to use this GitHub Action:

name: markdown-link-check

on:
  push:

jobs:
  markdown-link-check:
    name: Check markdown files
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Markdown links check
        uses: ruzickap/action-my-markdown-link-checker@v1

Parameters

Variables used by action-my-markdown-link-checker GitHub Action:

Variable	Default	Description
config_file	.mlc_config.json (if exists)	Config file used by markdown-link-check
debug	(not defined)	Enable debug mode for the entrypoint.sh script (set -x) and --verbose for markdown-link-check
exclude	(not defined)	Exclude files or directories - see the --exclude parameter of fd
fd_cmd_params	. -0 --extension md --type f --hidden --no-ignore	Set your own parameters for fd command. exclude and search_paths parameters are ignored if this is set.
quiet	(not defined)	Display errors only
search_paths	(not defined)	By default, all *.md files in the entire repository are checked. This parameter allows you to specify particular directories to search.
verbose	(not defined)	Displays detailed error information

None of the parameters listed above are mandatory.

If you need to exclude/ignore domains, add custom headers, or prevent specific URLs from being checked, use the config_file option for markdown-link-check. See the config file format documentation for details.

If a .mlc_config.json file is present in the root of your repository, it will be automatically used as the config_file.

Full GitHub Action Workflow Example

Full GitHub Action Workflow Example:

name: markdown-link-check

on:
  push:
    branches:
      - main

jobs:
  markdown-link-check:
  name: Check markdown files for broken links
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Markdown links check
        uses: ruzickap/action-my-markdown-link-checker@v1
        with:
          config_file: mlc_config.json
          debug: true
          exclude: |
            my_exclude_dir/md_files/
            my_exclude_dir_2/markdown_files/
            CHANGELOG.md
          search_paths: |
            check_dir_1/md_files/
            check_dir_2/markdown_files/

      - name: Markdown links check - check only 'docs' directory and exclude CHANGELOG.md
        uses: ruzickap/action-my-markdown-link-checker@v1
        with:
          search_paths: |
            docs/
          exclude: |
            CHANGELOG.md
          verbose: true

      - name: Markdown links check - simple example
        uses: ruzickap/action-my-markdown-link-checker@v1

      - name: Markdown links check using pre-built container
        uses: docker://peru/my-markdown-link-checker@v1

Example of Periodic Execution (Cron Job):

name: periodic-markdown-link-check

on:
  schedule:
    - cron: '8 8 * * 2'

jobs:
  markdown-link-check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Markdown links check
        uses: ruzickap/action-my-markdown-link-checker@v1

Running locally

You can also run the Markdown link checker locally using Docker:

docker run --rm -t -v "${PWD}/tests/test2:/mnt" peru/my-markdown-link-checker

Output:

*** Start checking...
*** Running: fd . -0 --extension md --type f --hidden --no-ignore
*** Running: markdown-link-check  normal.md

FILE: normal.md
[✓] https://google.com

1 links checked.


*** Checks completed...

Alternatively, you can use parameters with the Docker command:

export INPUT_EXCLUDE="CHANGELOG.md test1/excluded_file.md bad.md excluded_dir/"
export INPUT_SEARCH_PATHS="tests/"
export INPUT_VERBOSE="true"
docker run --rm -t -e INPUT_EXCLUDE -e INPUT_SEARCH_PATHS -e INPUT_VERBOSE -v "${PWD}:/mnt" peru/my-markdown-link-checker

Output:

*** Start checking...
*** Running: fd . -0 --extension md --type f --hidden --no-ignore --exclude CHANGELOG.md --exclude test1/excluded_file.md --exclude bad.md --exclude excluded_dir/ tests/
*** Running: markdown-link-check --verbose tests/test2/normal.md

FILE: tests/test2/normal.md
[✓] https://google.com → Status: 200

1 links checked.


*** Checks completed...

Example output for broken links:

docker run --rm -t -e INPUT_SEARCH_PATHS -e INPUT_VERBOSE -v "${PWD}:/mnt" peru/my-markdown-link-checker

Output:

*** Start checking...
*** Running: fd . -0 --extension md --type f --hidden --no-ignore tests/
*** Running: markdown-link-check --verbose tests/excluded_dir/excluded.md

FILE: tests/excluded_dir/excluded.md
[✓] https://google.com → Status: 200

1 links checked.


*** Running: markdown-link-check --verbose tests/test-bad-mdfile/bad.md

FILE: tests/test-bad-mdfile/bad.md
[✖] https://non-existing-domain.com → Status: 0 Error: getaddrinfo ENOTFOUND non-existing-domain.com
    at GetAddrInfoReqWrap.onlookup [as oncomplete] (dns.js:66:26) {
  errno: -3008,
  code: 'ENOTFOUND',
  syscall: 'getaddrinfo',
  hostname: 'non-existing-domain.com'
}

1 links checked.

ERROR: 1 dead links found!
[✖] https://non-existing-domain.com → Status: 0
*** ERROR: Something went wrong - see the errors above...

Demo:

Similar projects

• https://github.com/gaurav-nelson/github-action-markdown-link-check
  • Great project, but it lacked functionality to exclude or skip files when last checked (2020-07-20).
• https://github.com/ocular-d/md-linkcheck-action
  • Similar project, but it does not offer as many advanced features.
• https://github.com/peter-evans/link-checker