🚨 Update (May 2024)I have developed a new tool called Linkspector, which offers improved functionality and reduced false positives. I recommend using Linkspector for your needs, which is now the preferred and supported option. Try GitHub action Linkspector! |
This GitHub action checks all Markdown files in your repository for broken links. (Uses [tcort/markdown-link-check](https://github.com/tcort/markdown-link-check))
## How to use
1. Create a new file in your repository `.github/workflows/action.yml`.
1. Copy-paste the following workflow in your `action.yml` file:
```yml
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
```
### Real-life usage samples
Following is a list of some of the repositories which are using GitHub Action -
Markdown link check.
1. [netdata](https://github.com/netdata/netdata/blob/master/.github/workflows/docs.yml) 
1. [GoogleChrome/lighthouse (Weekly cron job)](https://github.com/GoogleChrome/lighthouse/blob/master/.github/workflows/cron-weekly.yml)
1. [tendermint/tendermint](https://github.com/tendermint/tendermint/blob/master/.github/workflows/markdown-links.yml)
1. [pyroscope-io/pyroscope](https://github.com/pyroscope-io/pyroscope/blob/main/.github/workflows/lint-markdown.yml)
If you are using this on production, consider [buying me a coffee](https://liberapay.com/gaurav-nelson/) ☕.
## Configuration
- [Custom variables](#custom-variables)
- [Scheduled runs](#scheduled-runs)
- [Disable check for some links](#disable-check-for-some-links)
- [Check only modified files in a pull request](#check-only-modified-files-in-a-pull-request)
- [Check multiple directories and files](#check-multiple-directories-and-files)
- [Status code 429: Too many requests](#too-many-requests)
- [GitHub links failure fix](#github-links-failure-fix)
### Custom variables
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](https://github.com/tcort/markdown-link-check#config-file-format) for markdown-link-check. You can use it to remove false-positives by specifying replacement patterns and ignore patterns. The filename is interpreted relative to the repository root.|`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](#check-multiple-directories-and-files) section for usage.| - |
#### Sample workflow with variables
```yml
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
```
### Scheduled runs
In addition to checking links on every push, or pull requests, its also a good
hygiene to check for broken links regularly as well. See
[Workflow syntax for GitHub Actions - on.schedule](https://help.github.com/en/actions/reference/workflow-syntax-for-github-actions#onschedule)
for more details.
#### Sample workflow with scheduled job
```yml
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'
```
### 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. `` and ``: Use these to disable links for all links appearing between these
comments.
- Example:
```md
## Section
Disbale link checking in this section. Ignore this [Bad Link](https://exampleexample.cox)
```
2. `` Use this comment to disable link checking for the next line.
3. `` 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 modified 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.
```yml
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'
```
### Check multiple directories and files
```yml
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'
```
### 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:
```json
{
"aliveStatusCodes": [429, 200]
}
```
### GitHub links failure fix
Use the following `httpHeaders` in your custom configuration file to fix GitHub links failure.
```json
{
"httpHeaders": [
{
"urls": ["https://github.com/", "https://guides.github.com/", "https://help.github.com/", "https://docs.github.com/"],
"headers": {
"Accept-Encoding": "zstd, br, gzip, deflate"
}
}
]
}
```
## Example Usage
Consider a workflow file that checks for the status of hyperlinks on push to the master branch,
``` yml
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
## Versioning
GitHub Action - Markdown link check follows the [GitHub recommended versioning strategy](https://github.com/actions/toolkit/blob/master/docs/action-versioning.md).
1. To use a specific released version of the action ([Releases](https://github.com/gaurav-nelson/github-action-markdown-link-check/releases)):
```yml
- uses: gaurav-nelson/github-action-markdown-link-check@1.0.1
```
1. To use a major version of the action:
```yml
- uses: gaurav-nelson/github-action-markdown-link-check@v1
```
1. You can also specify a [specific commit SHA](https://github.com/gaurav-nelson/github-action-markdown-link-check/commits/master) as an action version:
```yml
- uses: gaurav-nelson/github-action-markdown-link-check@44a942b2f7ed0dc101d556f281e906fb79f1f478
```
