remark-validate-links

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/foo.md#hello), 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

• Installation
• Command line
• Programmatic
• Configuration
• Integration
• Related
• Contribute
• 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
• remark-lint-no-dead-urls — Ensure external links are alive

Contribute

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

License

MIT © Titus Wormer