git.iko.soy/typeable/remark-validate-links
on 1.1.1 help sign in
typeable/remark-validate-links/readme.md
114 lines 3.3 kB history raw
1# mdast-validate-links [![Build Status](https://img.shields.io/travis/wooorm/mdast-validate-links.svg)](https://travis-ci.org/wooorm/mdast-validate-links) [![Coverage Status](https://img.shields.io/codecov/c/github/wooorm/mdast-validate-links.svg)](https://codecov.io/github/wooorm/mdast-validate-links)
3[**mdast**](https://github.com/wooorm/mdast) plug-in to validate if links to
4headings and files in markdown point to existing things.
6For example, this document does not have a heading named `Hello`. So if I
7link to that (`[welcome](#hello)`), this plug-in will warn about it.
9In addition, when I link to a heading in another document
10(`examples/foo.md#hello`), if this file exists but the heading does not,
11or if the file does not exist, this plug-in will also warn.
13Linking to other files, such as `LICENSE` or `index.js` (when they exist)
14is fine.
16## Table of Contents
18* [Installation](#installation)
19* [Command line](#command-line)
20* [Programmatic](#programmatic)
21* [Configuration](#configuration)
22* [Related](#related)
23* [License](#license)
25## Installation
27[npm](https://docs.npmjs.com/cli/install):
29```bash
30npm install mdast-validate-links
31```
33## Command line
35![Example of how mdast-validate-links looks on screen](https://cdn.rawgit.com/wooorm/mdast-validate-links/master/screenshot.png)
37Use **mdast-validate-links** together with [**mdast**](https://github.com/wooorm/mdast)
38and [**mdast-slug**](https://github.com/wooorm/mdast-slug):
40```bash
41npm install --global mdast mdast-slug mdast-validate-links
42```
44Let’s say `readme.md` is this document, and `example.md` looks as follows:
46```md
47# Hello
49Read more [whoops, this does not exist](#world).
51This doesn’t exist either [whoops!](readme.md#foo).
53But this does exist: [LICENSE](LICENSE).
55So does this: [README](readme.md#installation).
56```
58Then, to run **mdast-validate-links** on `example.md` and `readme.md`:
60```bash
61mdast -u mdast-slug -u mdast-validate-links example.md
63# Yields:
65# example.md
66# 3:11 warning Link to unknown heading: `world`
67# 5:27 warning Link to unknown heading in `readme.md`: `foo`
69# ✖ 2 problems (0 errors, 2 warnings)
70```
72## Programmatic
74This plug-in is **not** available on the API of mdast.
76## Configuration
78You can pass a `repository`, containing anything `package.json`s
79[`repository`](https://docs.npmjs.com/files/package.json#repository) can
80handle. If this is omitted, **mdast-validate-links** will try
81the `package.json` in your current working directory.
83```bash
84mdast --use 'validate-links=repository:"foo/bar"' example.md
85```
87When a repository is given or detected, links to GitHub are normalized
88to the file-system. E.g., `https://github.com/foo/bar/blob/master/example.md`
89becomes `example.md`.
91You can define this repository in `.mdastrc` or `package.json` [files](https://github.com/wooorm/mdast/blob/master/doc/mdastrc.5.md)
92too. An example `.mdastrc` file could look as follows:
94```json
96 "plugins": {
97 "slug": {
98 "library": "github"
99 },
100 "validate-links": {
101 "repository": "foo/bar"
102 }
103 }
105```
107## Related
109* [`mdast-lint`](https://github.com/wooorm/mdast-lint)
110 — Markdown code style linter.
112## License
114[MIT](LICENSE) © [Titus Wormer](http://wooorm.com)