Project: remarkjs/remark-validate-links

Package: remark-validate-links@11.0.1

  1. Dependents: 22
  2. remark plugin to validate links to headings and files
  1. remark 190
  2. unified 174
  3. plugin 137
  4. markdown 131
  5. mdast 85
  6. remark-plugin 73
  7. file 34
  8. heading 26
  9. link 15
  10. reference 9
  11. validate 5


Build Coverage Downloads Size Sponsors Backers Chat

remark plugin to validate that Markdown links and images reference existing local files and headings.

For example, this document does not have a heading named Hello. So if we’d link to it ([welcome](#hello)), we’d get a warning.

In addition, when there’s a link to a heading in another document (examples/foo.md#hello), if that file exists but the heading does not, or if that file does not exist, we’d also get a warning.

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

This plugin does not check external URLs (see remark-lint-no-dead-urls) or undefined references (see remark-lint-no-undefined-references).


This plugin is ready for the new parser in remark (remarkjs/remark#536). No change is needed: it works exactly the same now as it did before!



This package is ESM only: Node 12+ is needed to use it and it must be imported instead of required.


npm install remark-validate-links



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:

  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

Note: passing a file over stdin(4) may not work as expected, because it is not known where the file originates from.


Note: The API checks links to headings and files. It does not check headings in other files. In a browser, only local links to headings are checked.

This package exports no identifiers. The default export is remarkValidateLinks.

Say we have the following file, example.md:

# Alpha

Links are checked:

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

# Bravo

Headings in `readme.md` are [checked](readme.md#nosuchheading).
And [missing files are reported](missing-example.js).

Definitions are also checked:

[alpha]: #alpha
[charlie]: #charlie

References w/o definitions are not checked: [delta]

And our module, example.js, looks as follows:

import {readSync} from 'to-vfile'
import {reporter} from 'vfile-reporter'
import {remark} from 'remark'
import remarkValidateLinks from 'remark-validate-links'

const file = readSync('example.md')

  .process(file, (file) => {

Now, running node example yields:

    6:6-6:31  warning  Link to unknown heading: `does-not`         missing-heading  remark-validate-links
  11:5-11:53  warning  Link to unknown file: `missing-example.js`  missing-file     remark-validate-links
  16:1-16:20  warning  Link to unknown heading: `charlie`          missing-heading  remark-validate-links

⚠ 3 warnings

(Note that readme.md#nosuchheading is not warned about, because the API does not check headings in other Markdown files).


Typically, you don’t need to configure remark-validate-links, as it detects local Git repositories. If one is detected that references a known Git host (GitHub, GitLab, or Bitbucket), some extra links can be checked. If one is detected that does not reference a known Git host, local links still work as expected. If you’re not in a Git repository, you must pass repository: false explicitly.

You can pass a repository (string?, false). If repository is nullish, the Git origin remote is detected. If the repository resolves to something npm understands as a Git host such as GitHub, GitLab, or Bitbucket, full URLs to that host (say, https://github.com/remarkjs/remark-validate-links/readme.md#install) can also be checked.

remark --use 'validate-links=repository:"foo/bar"' example.md

For this to work, a root (string?) is also used, referencing the local Git root directory (the place where .git is). If both root and repository are nullish, the Git root is detected. If root is not given but repository is, file.cwd is used.

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

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

If you’re self-hosting a Git server, you can provide URL information directly, as urlConfig (Object).

For this repository, urlConfig looks as follows:

  // Domain of URLs:
  hostname: 'github.com',
  // Path prefix before files:
  prefix: '/remarkjs/remark-validate-links/blob/',
  // Prefix of headings:
  headingPrefix: '#',
  // Whether lines in files can be linked:
  lines: true

If this project were hosted on Bitbucket, it would be:

  hostname: 'bitbucket.org',
  prefix: '/remarkjs/remark-validate-links/src/',
  headingPrefix: '#markdown-header-',
  lines: false


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


remark-validate-links, in Node, accesses the file system based on user content, and this may be dangerous. In Node git remote and git rev-parse also runs for processed files.

The tree is not modified, so there are no openings for cross-site scripting (XSS) attacks.


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, organization, or community you agree to abide by its terms.


MIT © Titus Wormer