Home

Awesome

Test library workflow status

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-check

To install the command line tool globally, run:

npm install -g markdown-link-check

Run 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.md

Alternatively, 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

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:

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.md

Check links from a local markdown file

markdown-link-check ./README.md

Check links from a local markdown folder (recursive)

This checks all files in folder ./docs with file extension *.md:

markdown-link-check ./docs

The files can also be searched for and filtered manually:

find . -name \*.md -print0 | xargs -0 -n1 markdown-link-check

Usage

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}} replacement
Config file format

config.json:

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 test

License

See LICENSE.md