This GitHub action checks all Markdown files in your repository for broken links. (Uses tcort/markdown-link-check)
-
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
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 β.
- Custom variables
- Scheduled runs
- Disable check for some links
- Check only modified files in a pull request
- Status code 429: Too many requests
- GitHub links failure fix
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. | 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. | - |
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
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.
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'
You can include the following HTML comments into your markdown files to disable checking for certain links in a markdown document.
<!-- 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 -->
- Example:
<!-- markdown-link-check-disable-next-line -->
Use this comment to disable link checking for the next line.<!-- markdown-link-check-disable-line -->
Use this comment to disable link checking for the current line.
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 usingbase-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'
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'
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]
}
Use the folliwng 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"
}
}
]
}
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
GitHub Action - Markdown link check follows the GitHub recommended versioning strategy.
- To use a specific released version of the action (Releases):
- uses: gaurav-nelson/[email protected]
- 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