mdast-validate-links

mdast 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
• Related
• License

Installation

npm:

npm install mdast-validate-links

Command line

Use mdast-validate-links together with mdast and mdast-slug:

npm install --global mdast mdast-slug mdast-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 mdast-validate-links on example.md and readme.md:

mdast -u mdast-slug -u mdast-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 mdast.

Configuration

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

mdast --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 .mdastrc or package.json files too. An example .mdastrc file could look as follows:

{
  "plugins": {
    "slug": {
      "library": "github"
    },
    "validate-links": {
      "repository": "foo/bar"
    }
  }
}

Related

• mdast-lint — Markdown code style linter.

License

MIT © Titus Wormer