@@ -10,20 +10,22 @@
1010
1111[**remark**][remark] plugin to validate that Markdown links and images reference
1212existing local files and headings.
13−It does not check external URLs (see [`remark-lint-no-dead-urls`][no-dead-urls]
14−for that).
1513
1614For example, this document does not have a heading named `Hello`.
17−So if we link to that (`[welcome](#hello)`), this plugin will warn about it.
15+So if we’d link to it (`[welcome](#hello)`), we’d get a warning.
1816
1917In addition, when there’s a link to a heading in another document
20−(`examples/foo.md#hello`), if this file exists but the heading does not, or if
21−the file does not exist, this plugin will also warn.
18+(`examples/foo.md#hello`), if that file exists but the heading does not, or if
19+that file does not exist, we’d also get a warning.
2220
2321Linking to other files, such as `license` or `index.js` (when they exist) is
2422fine.
2523
26−## Table of Contents
24+This plugin does not check external URLs (see
25+[`remark-lint-no-dead-urls`][no-dead-urls]) or undefined references
26+(see [`remark-lint-no-undefined-references`][no-undef-refs]).
27+
28+## Contents
2729
2830* [Install](#install)
2931* [Use](#use)
@@ -63,7 +65,7 @@ Read more [whoops, this does not exist](#world).
6365
6466This doesn’t exist either [whoops!](readme.md#foo).
6567
66−But this does exist: [LICENSE](LICENSE).
68+But this does exist: [license](license).
6769
6870So does this: [README](readme.md#installation).
6971```
@@ -94,17 +96,22 @@ Say we have the following file, `example.md`:
9496```markdown
9597# Alpha
9698
99+Links are checked:
100+
97101This [exists](#alpha).
98102This [one does not](#does-not).
99−References and definitions are [checked][alpha] [too][charlie].
100103
101104# Bravo
102105
103−Headings in `readme.md` are [not checked](readme.md#bravo).
104−But [missing files are reported](missing-example.js).
106+Headings in `readme.md` are [checked](readme.md#nosuchheading).
107+And [missing files are reported](missing-example.js).
108+
109+Definitions are also checked:
105110
106111[alpha]: #alpha
107112[charlie]: #charlie
113+
114+References w/o definitions are not checked: [delta]
108115```
109116
110117And our script, `example.js`, looks as follows:
@@ -117,7 +124,7 @@ var links = require('remark-validate-links')
117124
118125remark()
119126 .use(links)
120− .process(vfile.readSync('example.md'), function(err, file) {
127+ .process(vfile.readSync('example.md'), function (err, file) {
121128 console.error(report(err || file))
122129 })
123130```
@@ -126,19 +133,22 @@ Now, running `node example` yields:
126133
127134```markdown
128135example.md
129− 4:6-4:31 warning Link to unknown heading: `does-not` missing-heading remark-validate-links
130− 10:5-10:53 warning Link to unknown file: `missing-example.js` missing-file remark-validate-links
131− 13:1-13:20 warning Link to unknown heading: `charlie` missing-heading remark-validate-links
136+ 6:6-6:31 warning Link to unknown heading: `does-not` missing-heading remark-validate-links
137+ 11:5-11:53 warning Link to unknown file: `missing-example.js` missing-file remark-validate-links
138+ 16:1-16:20 warning Link to unknown heading: `charlie` missing-heading remark-validate-links
132139
133140⚠ 3 warnings
134141```
135142
143+(Note that `readme.md#nosuchheading` is not warned about, because the API
144+does not check headings in other Markdown files).
145+
136146## Configuration
137147
138148Typically, you don’t need to configure `remark-validate-links`, as it detects
139149local Git repositories.
140−If one is detected that references a known Git host, some extra links can be
141−checked.
150+If one is detected that references a known Git host (GitHub, GitLab,
151+or Bitbucket), some extra links can be checked.
142152If one is detected that does not reference a known Git host, local links still
143153work as expected.
144154If you’re not in a Git repository, you must pass `repository: false` explicitly.
@@ -296,6 +306,8 @@ abide by its terms.
296306
297307[no-dead-urls]: https://github.com/davidtheclark/remark-lint-no-dead-urls
298308
309+[no-undef-refs]: https://github.com/remarkjs/remark-lint/tree/master/packages/remark-lint-no-undefined-references
310+
299311[package-repository]: https://docs.npmjs.com/files/package.json#repository
300312
301313[cwd]: https://github.com/vfile/vfile#vfilecwd