This GitHub action checks all Markdown files in your repository for broken links. It has been especially designed for mkdocs, but can also work for any markdown-based website.
This action uses byrnereese/linkchecker-mkdocs, and is heavily inspired by:
-
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: mkdocs-link-check: runs-on: ubuntu-latest steps: - uses: actions/checkout@master - uses: byrnereese/github-action-mkdocs-link-check@v1
Following is a list of some of the repositories which are using GitHub Action - Markdown link check.
(Edit this file and add your name here)
You customize the action by using the following variables:
Variable | Description | Default value |
---|---|---|
excludes |
One or more patterns to identify links that can be excluded or skipped in your tests. | None |
file-extension |
By default the github-action-mkdocs-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 |
folder-path |
By default the github-action-mkdocs-link-check action checks for all markdown files in your repository, which typically are located in the docs directory for mkdocs projects. Use this option to limit checks to only specific folders. |
docs/ |
local-only |
Process local and relative links. No external or remote links will be tested. This speeds up processing considerably. | false |
method |
The HTTP method used for testing remote link validity. The GET method is more reliable, but much slower. | get |
recurse |
Recurse through the entire directory tree below the specified path. | true |
verbose-mode |
Specify yes to show detailed HTTP status for checked links. |
no |
name: Check Markdown links
on: push
jobs:
markdown-link-check:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@master
- uses: byrnereese/github-action-mkdocs-link-check@v1
with:
use-verbose-mode: 'yes'
folder-path: 'docs/'
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: byrnereese/github-action-mkdocs-link-check@v1
with:
use-verbose-mode: 'yes'
folder-path: 'docs/'
on: [pull_request]
name: Check links for modified files
jobs:
markdown-link-check:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@master
- uses: byrnereese/github-action-mkdocs-link-check@v1
with:
use-quiet-mode: 'yes'
folder-path: 'md/dir1, md/dir2'
file-path: './README.md, ./LICENSE, ./md/file4.markdown'
GitHub Action - Markdown link check follows the GitHub recommended versioning strategy.
- To use a specific released version of the action (Releases):
- uses: byrnereese/github-action-mkdocs-link-check@1.0.1
- To use a major version of the action:
- uses: byrnereese/github-action-mkdocs-link-check@v1
- You can also specify a specific commit SHA as an action version:
- uses: byrnereese/github-action-mkdocs-link-check@44a942b2f7ed0dc101d556f281e906fb79f1f478