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 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).

Then, to run remark-validate-links on example.md and readme.md:

remark -u remark-validate-links example.md
#
# Yields:
#
# example.md
#   3:11  warning  Link to unknown heading: `world`
#   5:27  warning  Link to unknown heading in `readme.md`: `foo`
#
# ✖ 2 problems (0 errors, 2 warnings)

Programmatic

This plug-in is not available on the API of remark.

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, links to GitHub are normalized to the file-system. E.g., 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.htmlAttributes.name — Used by remark-html to create a name attribute, which anchors can link to;
• node.data.htmlAttributes.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

• wooorm/remark-lint — Markdown code style linter.

License

MIT © Titus Wormer