tcort
markdown-link-check
Extracts links from markdown texts and checks whether each link is
alive (200 OK) or dead. mailto: links are validated with
isemail.
Installation
To add the module to your project, run:
npm install --save-dev markdown-link-checkTo install the command line tool globally, run:
npm install -g markdown-link-checkRun using Docker
Docker images are built with each release. Use the stable tag for the current stable release.
Add current directory with your README.md file as read only volume to docker run:
docker run -v ${PWD}:/tmp:ro --rm -i ghcr.io/tcort/markdown-link-check:stable /tmp/README.mdAlternatively, if you wish to target a specific release, images are tagged with semantic versions (i.e. 3, 3.8, 3.8.3)
Run in a GitHub action
Please head on to github-action-markdown-link-check.
Run as a pre-commit hook
To run as a pre-commit hook:
- repo: https://github.com/tcort/markdown-link-check
rev: ...
hooks:
- id: markdown-link-check
args: [-q]Run in a GitLab pipeline
linkchecker:
stage: test
image:
name: ghcr.io/tcort/markdown-link-check:3.11.2
entrypoint: ["/bin/sh", "-c"]
script:
- markdown-link-check ./docs
rules:
- changes:
- "**/*.md"Run in other tools
- Mega-Linter: Linters aggregator including markdown-link-check
API
markdownLinkCheck(markdown, [opts,] callback)
Given a string containing markdown formatted text and a callback,
extract all of the links and check if they're alive or dead. Call the
callback with (err, results)
Parameters:
markdownstring containing markdown formatted text.optsoptional options object containing any of the following optional fields:showProgressBarenable an ASCII progress bar.timeouttimeout in zeit/ms format. (e.g."2000ms",20s,1m). Default10s.httpHeadersto apply URL specific headers, see example below.ignorePatternsan array of objects holding regular expressions which a link is checked against and skipped for checking in case of a match. Example:[{ pattern: /foo/ }]replacementPatternsan array of objects holding regular expressions which are replaced in a link with their corresponding replacement string. This behavior allows (for example) to adapt to certain platform conventions hosting the Markdown. The special replacement{{BASEURL}}can be used to dynamically link to the base folder (used fromprojectBaseUrl) (for example that/points to the root of your local repository). Example:[{ pattern: /^.attachments/, replacement: "file://some/conventional/folder/.attachments" }, { pattern: ^/, replacement: "{{BASEURL}}/"}]. You can add"global": trueto use a global regular expression to replace all instances.projectBaseUrlthe URL to use for{{BASEURL}}replacementignoreDisableif this istruethen disable comments are ignored.retryOn429if this istruethen retry request when response is an HTTP code 429 after the duration indicated byretry-afterheader.retryCountthe number of retries to be made on a 429 response. Default2.fallbackRetryDelaythe delay in zeit/ms format. (e.g."2000ms",20s,1m) for retries on a 429 response when noretry-afterheader is returned or when it has an invalid value. Default is60s.aliveStatusCodesa list of HTTP codes to consider as alive. Example:[200,206]
callbackfunction which accepts(err, results).erran Error object when the operation cannot be completed, otherwisenull.resultsan array of objects with the following properties:linkthelinkprovided as inputstatusa string set to eitheralive,ignoredordead.statusCodethe HTTP status code. Set to0if no HTTP status code was returned (e.g. when the server is down).errany connection error that occurred, otherwisenull.
Disable comments
You can write html comments to disable markdown-link-check for parts of the text.
<!-- markdown-link-check-disable --> disables markdown link check.
<!-- markdown-link-check-enable --> reenables markdown link check.
<!-- markdown-link-check-disable-next-line --> disables markdown link check for the next line.
<!-- markdown-link-check-disable-line --> disables markdown link check for this line.
Examples
Module
Basic usage:
'use strict';
var markdownLinkCheck = require('markdown-link-check');
markdownLinkCheck('[example](http://example.com)', function (err, results) {
if (err) {
console.error('Error', err);
return;
}
results.forEach(function (result) {
console.log('%s is %s', result.link, result.status);
});
});With options, for example using URL specific headers:
'use strict';
var markdownLinkCheck = require('markdown-link-check');
markdownLinkCheck('[example](http://example.com)', { httpHeaders: [{ urls: ['http://example.com'], headers: { 'Authorization': 'Basic Zm9vOmJhcg==' }}] }, function (err, results) {
if (err) {
console.error('Error', err);
return;
}
results.forEach(function (result) {
console.log('%s is %s', result.link, result.status);
});
});Command Line Tool
The command line tool optionally takes 1 argument, the file name or http/https URL. If not supplied, the tool reads from standard input.
Check links from a markdown file hosted on the web
markdown-link-check https://github.com/tcort/markdown-link-check/blob/master/README.mdCheck links from a local markdown file
markdown-link-check ./README.mdCheck links from a local markdown folder (recursive)
This checks all files in folder ./docs with file extension *.md:
markdown-link-check ./docsThe files can also be searched for and filtered manually:
find . -name \*.md -print0 | xargs -0 -n1 markdown-link-checkUsage
Usage: markdown-link-check [options] [filenameOrDirectorynameOrUrl]
Options:
-p, --progress show progress bar
-c, --config [config] apply a config file (JSON), holding e.g. url specific header configuration
-q, --quiet displays errors only
-v, --verbose displays detailed error information
-a, --alive <code> comma separated list of HTTP code to be considered as alive
-r, --retry retry after the duration indicated in 'retry-after' header when HTTP code is 429
-h, --help display help for command
-V, --version display version string (e.g. `1.2.3`)
, --projectBaseUrl <url> the URL to use for {{BASEURL}} replacementConfig file format
config.json:
ignorePatterns: An array of objects holding regular expressions which a link is checked against and skipped for checking in case of a match.replacementPatterns: An array of objects holding regular expressions which are replaced in a link with their corresponding replacement string. This behavior allows (for example) to adapt to certain platform conventions hosting the Markdown. The special replacement{{BASEURL}}can be used to dynamically link to the current working directory (for example that/points to the root of your current working directory). This parameter supports named regex groups the same way asstring.replacemethod in node.httpHeaders: The headers are only applied to links where the link starts with one of the supplied URLs in theurlssection.timeouttimeout in zeit/ms format. (e.g."2000ms",20s,1m). Default10s.retryOn429if this istruethen retry request when response is an HTTP code 429 after the duration indicated byretry-afterheader.retryCountthe number of retries to be made on a 429 response. Default2.fallbackRetryDelaythe delay in zeit/ms format. (e.g."2000ms",20s,1m) for retries on a 429 response when noretry-afterheader is returned or when it has an invalid value. Default is60s.aliveStatusCodesa list of HTTP codes to consider as alive.projectBaseUrlthe URL to use for{{BASEURL}}replacement
Example:
{
"projectBaseUrl":"${workspaceFolder}",
"ignorePatterns": [
{
"pattern": "^http://example.net"
}
],
"replacementPatterns": [
{
"pattern": "^.attachments",
"replacement": "file://some/conventional/folder/.attachments"
},
{
"pattern": "^/",
"replacement": "{{BASEURL}}/"
},
{
"pattern": "%20",
"replacement": "-",
"global": true
},
{
"pattern": "images/(?<filename>.*)",
"replacement": "assets/$<filename>"
}
],
"httpHeaders": [
{
"urls": ["https://example.com"],
"headers": {
"Authorization": "Basic Zm9vOmJhcg==",
"Foo": "Bar"
}
}
],
"timeout": "20s",
"retryOn429": true,
"retryCount": 5,
"fallbackRetryDelay": "30s",
"aliveStatusCodes": [200, 206]
}Testing
npm testLicense
See LICENSE.md