Skip to content
list

GitHub Action

My Markdown Link Checker

v1.3.0 Latest version

My Markdown Link Checker

list

My Markdown Link Checker

Check markdown files for broken links

Installation

Copy and paste the following snippet into your .yml file.

 
              
- name: My Markdown Link Checker

              
  uses: ruzickap/action-my-markdown-link-checker@v1.3.0
Learn more about this action in ruzickap/action-my-markdown-link-checker

Choose a version

GitHub Actions: My Markdown Link Checker ✔

GitHub Marketplace license release GitHub release date GitHub Actions status Docker Hub Build Status

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:

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

None 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@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 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@v4

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

My Markdown Link Checker

Similar projects