Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/ruzickap/action-my-markdown-link-checker
A GitHub Action for checking broken links in Markdown files
https://github.com/ruzickap/action-my-markdown-link-checker
actions broken-links checker github-action github-actions link-checker link-checking links markdown url-check url-checker website
Last synced: about 2 months ago
JSON representation
A GitHub Action for checking broken links in Markdown files
- Host: GitHub
- URL: https://github.com/ruzickap/action-my-markdown-link-checker
- Owner: ruzickap
- License: apache-2.0
- Created: 2020-07-18T05:02:16.000Z (over 4 years ago)
- Default Branch: main
- Last Pushed: 2024-10-27T03:19:30.000Z (about 2 months ago)
- Last Synced: 2024-10-27T03:24:21.780Z (about 2 months ago)
- Topics: actions, broken-links, checker, github-action, github-actions, link-checker, link-checking, links, markdown, url-check, url-checker, website
- Language: Shell
- Homepage:
- Size: 186 KB
- Stars: 19
- Watchers: 4
- Forks: 7
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
- Codeowners: .github/CODEOWNERS
Awesome Lists containing this project
- project-awesome - ruzickap/action-my-markdown-link-checker - A GitHub Action for checking broken links in Markdown files (Shell)
README
# GitHub Actions: My Markdown Link Checker ✔
[](https://github.com/marketplace/actions/my-markdown-link-checker)
[](https://github.com/ruzickap/action-my-markdown-link-checker/blob/main/LICENSE)
[](https://github.com/ruzickap/action-my-markdown-link-checker/releases/latest)
[](https://github.com/ruzickap/action-my-markdown-link-checker/releases)
[](https://hub.docker.com/r/peru/my-markdown-link-checker)
This is a GitHub Action to check Markdown files for broken links.
It's using the [markdown-link-check](https://github.com/tcort/markdown-link-check)
and [fd](https://github.com/sharkdp/fd).
See the basic GitHub Action example:
```yaml
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](https://github.com/tcort/markdown-link-check#config-file-format) used by [markdown-link-check](https://github.com/tcort/markdown-link-check) |
| `debug` | (not defined) | Enable debug mode for the [entrypoint.sh](entrypoint.sh) script (`set -x`) and `--verbose` for [markdown-link-check](https://github.com/tcort/markdown-link-check) |
| `exclude` | (not defined) | Exclude files or directories - see the [--exclude parameter](https://github.com/sharkdp/fd#excluding-specific-files-or-directories) of [fd](https://github.com/sharkdp/fd) command |
| `fd_cmd_params` | `. -0 --extension md --type f --hidden --no-ignore` | Set your own parameters for [fd](https://github.com/sharkdp/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](https://github.com/tcort/markdown-link-check#config-file-format)
for [markdown-link-check](https://github.com/tcort/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:
```yaml
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):
```yaml
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:
```bash
docker run --rm -t -v "${PWD}/tests/test2:/mnt" peru/my-markdown-link-checker
```
Output:
```text
*** 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:
```bash
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:
```text
*** 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:
```shell
docker run --rm -t -e INPUT_SEARCH_PATHS -e INPUT_VERBOSE -v "${PWD}:/mnt" peru/my-markdown-link-checker
```
Output:
```text
*** 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:
[](https://asciinema.org/a/348733)
## Similar projects
* [https://github.com/gaurav-nelson/github-action-markdown-link-check](https://github.com/gaurav-nelson/github-action-markdown-link-check)
* great project with missing "exclude/skip files" functionality (as of now 2020-07-20)
* [https://github.com/ocular-d/md-linkcheck-action](https://github.com/ocular-d/md-linkcheck-action)
* similar project with not enough advanced features
* [https://github.com/peter-evans/link-checker](https://github.com/peter-evans/link-checker)