remark-validate-links

remark-validate-links

remark plugin to validate that Markdown links and images reference existing local files and headings. 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

• Install
• Use
  • CLI
  • API
• Configuration
• Integration
• Related
• Contribute
• License

Install

npm:

npm install remark-validate-links

Use

CLI

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

API

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 not given, remark-validate-links will try the package.json in the 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/.github for ways to get started. See support.md for ways to get help.

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

License

MIT © Titus Wormer