Validate if links point to existing headings and files in markdown
Clone or download
Latest commit 8aa3d19 Aug 13, 2018

remark-validate-links Build Status Coverage Status Chat

remark plugin to validate if internal links to headings and files in markdown point to existing things. It does not check external URLs (see remark-lint-no-dead-urls for that).

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

In addition, when I link to a heading in another document (examples/, if this file exists but the heading does not, or if the file does not exist, this plugin will also warn.

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

Table of Contents



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 is this document, and looks as follows:

# Hello

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

This doesn’t exist either [whoops!](

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

So does this: [README](

Now, running remark -u validate-links . yields:
  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 ``: `foo`  missing-heading-in-file  remark-validate-links no issues found

⚠ 2 warnings


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

Say we have the following file,

# Alpha

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

# Bravo

This is [not checked](

[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')

  .process(vfile.readSync(''), function(err, file) {
    console.error(report(err || file))

Now, running node example yields:
  4:6-4:31  warning  Link to unknown heading: `does-not`  remark-validate-links  remark-validate-links

⚠ 1 warning


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"'

When a repository is given or detected (supporting GitHub, GitLab, and Bitbucket), links to the files are normalized to the file-system. For example, becomes

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

  "plugins": [
        "repository": "foo/bar"


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

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



See in remarkjs/remark for ways to get started.

This organisation has a Code of Conduct. By interacting with this repository, organisation, or community you agree to abide by its terms.


MIT © Titus Wormer