Skip to content
Go to file

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time


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




npm install remark-validate-links



Use remark-validate-links together with remark:

npm install --global remark-cli remark-validate-links

Let’s say is this document, and looks as follows:

# Hello

Read more [whoops, this does not exist](#world).

This doesn’t exist either [whoops!](

But this does exist: [license](license).

So does this: [README](

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 ``: `foo`  missing-heading-in-file  remark-validate-links 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.

Say we have the following file,

# Alpha

Links are checked:

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

# Bravo

Headings in `` are [checked](
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 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')

  .process(vfile.readSync(''), function (err, file) {
    console.error(report(err || 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 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, can also be checked.

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

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: '',
  // 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: '',
  prefix: '/remarkjs/remark-validate-links/src/',
  headingPrefix: '#markdown-header-',
  lines: false


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

  • — Used by remark-html to create a name attribute, which anchors can link to
  • — Used by remark-html to create an id attribute, which anchors can link to
  • — Used, in the future, by other tools to signal unique identifiers 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 in remarkjs/.github for ways to get started. See 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

You can’t perform that action at this time.