This GitHub action checks all hyperlinks in Markdown files for broken links and reports their status. It's designed to be lightweight, fast, and compatible across different environments.
- Checks external URLs and reports HTTP status codes
- Validates internal file links and fragment references
- Supports checking image links
- Recursive directory scanning
- Configurable timeout and retry settings
- Detailed reporting of broken links
name: Check Markdown links
on:
push:
branches: [main]
pull_request:
branches: [main]
schedule:
# Run weekly on Sundays
- cron: "0 0 * * 0"
jobs:
check-links:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Check Markdown Links
uses: harryvasanth/markdown-link-checker@v1
name: Check Markdown links
on:
push:
branches: [main]
jobs:
check-links:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Check Markdown Links
uses: harryvasanth/markdown-link-checker@v1
with:
path: "docs"
files: "README.md,CONTRIBUTING.md"
exclude: "node_modules,vendor"
recursive: "true"
timeout: "15"
retry-count: "3"
verbose: "true"
Input | Description | Required | Default |
---|---|---|---|
path |
Path to check for markdown files | No | . |
files |
Specific markdown files to check (comma-separated) | No | |
exclude |
Files or directories to exclude (comma-separated) | No | |
recursive |
Check files recursively | No | true |
timeout |
Timeout for HTTP requests in seconds | No | 10 |
retry-count |
Number of retries for failed requests | No | 3 |
verbose |
Show detailed output | No | false |
config-file |
Path to configuration file | No |
You can use a configuration file to set options for the link checker. Create a file (e.g., .linkcheck.conf
) with the following format:
# Link Checker Configuration
PATH_TO_CHECK="docs"
EXCLUDE="node_modules,vendor"
TIMEOUT=15
RETRY_COUNT=3
VERBOSE=true
Then reference it in your workflow:
- name: Check Markdown Links
uses: harryvasanth/markdown-link-checker@v1
with:
config-file: ".linkcheck.conf"
The action will output information about the links it checks and any broken links it finds:
=== Markdown Link Checker ===
Starting link check process...
Checking links in README.md
Found 15 links in README.md
Checking links in docs/guide.md
β docs/guide.md:25 - Broken link: https://example.com/broken-link (Status: 404)
β docs/guide.md:42 - Broken link: ./non-existent-file.md (File not found: docs/non-existent-file.md)
Found 10 links in docs/guide.md
=== Link Check Summary ===
Files checked: 2
Total links: 25
β Found 2 broken links!