search

tcort / markdown-link-check

checks all of the hyperlinks in a markdown text to determine if they are alive or dead
ISC License
561 stars 116 forks source link
checker hyperlinks markdown

readme

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:
    - find . -name \*.md -print0 | xargs -0 -n1 markdown-link-check
  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)

Avoid using find -exec because it will swallow the error from each consecutive run. Instead, use xargs:

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

There is an open issue for allowing the tool to specify multiple files on the command line.

Usage

Usage: markdown-link-check [options] [filenameOrUrl]

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
    }
  ],
  "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