sotayamashita/action-my-markdown-link-checker

A GitHub Action for checking broken links in Markdown files

GitHub Actions: My Markdown Link Checker ✔

This is a GitHub Action to check Markdown files for broken links. It's using the markdown-link-check and fd.

See the basic GitHub Action example:

name: markdown-link-check

on:
  push:

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

      - 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 command
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 are checked in whole repository, but you can specify directories
verbose	(not defined)	Displays detailed error information

Non of the parameters above are "mandatory".

In case you need to exclude/ignore some domains, add headers, form being checked you need to use the config_file for markdown-link-check.

If .mlc_config.json is found in the root of the repository it's automatically used as config_file.

Full example

GitHub Action 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@v2

      - 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 with periodic runs (run as Cron):

name: periodic-markdown-link-check

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

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

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

Running locally

It's possible to use the Markdown link checks 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...

Or you can also use parameters:

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...

The example with broken links may look like:

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:

Examples

• Periodic checks

  Repository	Code	GitHub Action
  packer-tamplates	periodic-markdown-links-check.yml	periodic-markdown-links-check/markdown-link-check/Link Checker

• Markdown checks

  Repository	Code	GitHub Action
  k8s-istio-demo	checks.yml	checks/markdown-link-check/Link Checker
  action-my-markdown-linter	markdown.yml	markdown/markdown-link-check/Link Checker

Similar projects

• https://github.com/gaurav-nelson/github-action-markdown-link-check
  • great project with missing "exclude/skip files" functionality (as of now 2020-07-20)
• https://github.com/ocular-d/md-linkcheck-action
  • similar project with not enough advanced features
• https://github.com/peter-evans/link-checker