remark-validate-links

remark plug-in to validate if links to headings and files in markdown point to existing things.

For example, this document does not have a heading named Hello. So if I link to that ([welcome](#hello)), this plug-in will warn about it.

In addition, when I link to a heading in another document (examples/foo.md#hello), if this file exists but the heading does not, or if the file does not exist, this plug-in will also warn.

Linking to other files, such as LICENSE or index.js (when they exist) is fine.

Table of Contents

• Installation
• Command line
• Programmatic
• Configuration
• Integration
• Related
• License

Installation

npm:

npm install remark-validate-links

Command line

Use remark-validate-links together with remark:

npm install --global remark-cli remark-validate-links

Let’s say readme.md is this document, and example.md looks as follows:

# Hello

Read more [whoops, this does not exist](#world).

This doesn’t exist either [whoops!](readme.md#foo).

But this does exist: [LICENSE](LICENSE).

So does this: [README](readme.md#installation).

Now, running remark -u validate-links . yields:

example.md
  3:11-3:48  warning  Link to unknown heading: `world`               missing-heading          remark-validate-links
  5:27-5:51  warning  Link to unknown heading in `readme.md`: `foo`  missing-heading-in-file  remark-validate-links

readme.md: no issues found

⚠ 2 warnings

Programmatic

Note: The API only checks links to headings. Other URLs are not checked.

Say we have the following file, example.md:

# Alpha

This [exists](#alpha). This [exists][alpha] too.
This [one does not](#does-not).

# Bravo

This is [not checked](readme.md#bravo).

[alpha]: #alpha

And our script, example.js, looks as follows:

var vfile = require('to-vfile');
var report = require('vfile-reporter');
var remark = require('remark');
var links = require('remark-validate-links');

remark()
  .use(links)
  .process(vfile.readSync('example.md'), function (err, file) {
    console.error(report(err || file));
  });

Now, running node example yields:

example.md
  4:6-4:31  warning  Link to unknown heading: `does-not`  remark-validate-links  remark-validate-links

⚠ 1 warning

Configuration

You can pass a repository, containing anything package.jsons repository can handle. If this is omitted, remark-validate-links will try the package.json in your current working directory.

remark --use 'validate-links=repository:"foo/bar"' example.md

When a repository is given or detected (supporting GitHub, GitLab, and Bitbucket), links to the files are normalized to the file-system. For example, https://github.com/foo/bar/blob/master/example.md becomes example.md.

You can define this repository in configuration files too. An example .remarkrc file could look as follows:

{
  "plugins": [
    [
      "validate-links",
      {
        "repository": "foo/bar"
      }
    ]
  ]
}

Integration

remark-validate-links can detect anchors on nodes through several properties on nodes:

• node.data.hProperties.name — Used by remark-html to create a name attribute, which anchors can link to
• node.data.hProperties.id — Used by remark-html to create an id attribute, which anchors can link to
• node.data.id — Used, in the future, by other tools to signal unique identifiers on nodes

Related

• remark-lint — Markdown code style linter

License

MIT © Titus Wormer