Table of Contents
The Dead Link Linter is a small executable that will crawl through your directory(ies) to ensure that all external links embedded in your documentation work as intended. This can be used to ensure embedded media works as intended, or can ensure that embedded hyperlinks land where they are supposed to.
Software projects typically have additional software projects that they are built upon, or utilize in some way. This usually leads to referencing documentation from other projects in your projects. Since we often aren't maintainers of the projects referenced, the Dead Link Linter can be added as a Continous Integration gate in your CI/CD system to ensure these external references to not go stale, and if they are stale, they can be identified and updated quickly.
The following will download, run, report, and remove the Dead Link Linter, leaving you with the results
# For (Debian) Linux
curl https://raw.githubusercontent.com/DannyMassa/dead-link-linter/master/scripts/linux/dead-link-linter-single-run.sh | bash
# For Windows
curl https://raw.githubusercontent.com/DannyMassa/dead-link-linter/master/scripts/windows/dead-link-linter-single-run.sh | bashNone! The Dead Link Linter runs as a standalone executable, but cURL or a similar alternative is required if running the application using the command provided in the TL;DR
There are two simple ways to install/use the Dead Link Linter: As a single use script or as a portable executable located in the directory you are executing from.
Briefly referenced in the TL;DR, this is the simpliest way to try the Dead Link Linter. This script was created to allow users to quickly download the executable, run the service, and remove all related files. The limitation being that since the linter is not executed directly by the user, CLI overrides will not be available. .deadlink files are utilized if they reside in the directory the script is called from.
TODO INSERT GIF
From the Releases page, download the artifact that matches your machine. It is always recommended that you download the latest release. Unpack the resulting compressed artifact, and move the executable from the extracted directory to the directory you intend on executing it from. From your shell, navigate to that directory and utilize the CLI commands to execute
TODO INSERT GIF
The Dead Link Linter offers a usable set of default values but is highly configurable. Configuration using CLI flags takes priority over a .deadlink file, and a .deadlink file will take priority over default values.
The Dead Link Linter does not require any parameters to be supplied via CLI in order to run, but supplying command line arguements will overwrite any configuration settings provided by a .deadlink file, and will also override any defaults. CLI command syntax follows POSIX/GNU-style flags.
# Run with defaults
$ ./dead-link-linter
# Allow up to 10 links to be dead, and only scan files with an '.md' extension
$ ./dead-link-linter --max_failures=10 --file_extensions=[".md"]
# Use an alternative golden URL if google.com doesn't suit your needs
$ ./dead-link-linter --golden_url="https://bing.com"
# Ignore search engine links
$ ./dead-link-linter --ignored=["https://bing.com", "https://google.com"]
# Only print failure logs
$ ./dead-link-linter --log_verbosity=0Automatically, the Dead Link Linter looks for a file named .deadlink in the directory the linter is being executed from. .deadlink should be a valid YAML file. If the file is found, the configuration will be loaded and parsed. If the YAML is not successfully parsed, the application will exit with an unhealthy status code before any links are checked.
directories:
- "./"
fileExtensions:
- ".md"
goldenURL: "https://google.com"
ignored:
- "https://google.com"
maxFailures: 0
logVerbosity: 1
# In this case, individualTimeout is omitted, therefore the timeout will remain the default value of 10 seconds, unless the CLI flag (--individual_timeout) is set to another value| YAML Key | CLI | Default | [Domain] Description |
|---|---|---|---|
| directories | --directories | ["./"] | A list of (string) directories to run the linter against relative and absolute paths. Overlapping files will be checked in each directory section (multiple times) and all subdirectories will be recursively included. |
| fileExtensions | --file_extensions | [".markdown", ".mdown", ".mkdn", ".md", ".mkd", ".mdwn", ".mdtxt", ".mdtext", ".text", ".txt", ".rst"] | A list of (string) file extensions that indicates what file types will be scanned during the linter's run. All strings must begin with a . |
| goldenURL | --golden_url | https://google.com | A url that will be tested first, and upon failure will cause an unhealthy exit from the program (exit code 5). This is a 'fail fast' mechanism. |
| ignored | --ignored | [] | A list of (string) URLs that will be ignored if they are found by the URL parser. This is the suggested way to manage false positives. i.e. example URLs & example IP Addresses from your documentation. |
| individualTimeout | --individual_timeout | 10 | [1, 2147483647) The amount of time, in seconds, allowed for a web request |
| maxFailures | --max_failures | 0 | [0, 2147483647) The number of URLs allowed to have a FAILURE status before the linter exits with an unhealthy code. (exit code 1) |
| logVerbosity | --log_verbosity | 1 | [0, 2] a numerical value describing if detailed logs are printed. 0 indicates failure only logs, 1 indicates skipped urls will be included, 2 indicates success urls will be included |
See the open issues for a list of proposed features (and known issues).
- Top Feature Requests (Add your votes using the 👍 reaction)
- Top Bugs (Add your votes using the 👍 reaction)
First off, thanks for taking the time to contribute! Contributions are what make the open-source community such an amazing place to learn, inspire, and create. Any contributions you make will benefit everybody else and are greatly appreciated.
We have set up a separate document containing our contribution guidelines.
Thank you for being involved!
The original setup of this repository is by Danny Massa.
For a full list of all authors and contributors, check the contributor's page.
Dead Link Linter follows good practices of security, but 100% security can't be granted in software. Dead Link Linter is provided "as is" without any warranty. Use at your own risk.
This project is licensed under the MIT license.
See LICENSE for more information.