-
Notifications
You must be signed in to change notification settings - Fork 120
/
Copy pathREADME.md
228 lines (172 loc) · 8.69 KB
/
README.md
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
# markdown-link-check
Extracts links from markdown texts and checks whether each link is
alive (`200 OK`) or dead. `mailto:` links are validated with
[isemail](https://www.npmjs.com/package/isemail).
## Installation
To add the module to your project, run:
```shell
npm install --save-dev markdown-link-check
```
To install the command line tool globally, run:
```shell
npm install -g markdown-link-check
```
---
## Run using Docker
Docker images are built with each release. Use the `stable` tag for the current stable release.
Add current directory with your `README.md` file as read only volume to `docker run`:
```shell
docker run -v ${PWD}:/tmp:ro --rm -i ghcr.io/tcort/markdown-link-check:stable /tmp/README.md
```
Alternatively, if you wish to target a specific release, images are tagged with semantic versions (i.e. `3`, `3.8`, `3.8.3`)
## Run in a GitHub action
Please head on to [github-action-markdown-link-check](https://github.com/gaurav-nelson/github-action-markdown-link-check).
## Run in other tools
- [Mega-Linter](https://nvuillam.github.io/mega-linter/): Linters aggregator [including markdown-link-check](https://nvuillam.github.io/mega-linter/descriptors/markdown_markdown_link_check/)
## API
### markdownLinkCheck(markdown, [opts,] callback)
Given a string containing `markdown` formatted text and a `callback`,
extract all of the links and check if they're alive or dead. Call the
`callback` with `(err, results)`
Parameters:
* `markdown` string containing markdown formatted text.
* `opts` optional options object containing any of the following optional fields:
* `baseUrl` the base URL for relative links.
* `showProgressBar` enable an ASCII progress bar.
* `timeout` timeout in [zeit/ms](https://www.npmjs.com/package/ms) format. (e.g. `"2000ms"`, `20s`, `1m`). Default `10s`.
* `httpHeaders` to apply URL specific headers, see example below.
* `ignorePatterns` an array of objects holding regular expressions which a link is checked against and skipped for checking in case of a match. Example: `[{ pattern: /foo/ }]`
* `replacementPatterns` an array of objects holding regular expressions which are replaced in a link with their corresponding replacement string. This behavior allows (for example) to adapt to certain platform conventions hosting the Markdown. The special replacement `{{BASEURL}}` can be used to dynamically link to the base folder (used from `projectBaseUrl`) (for example that `/` points to the root of your local repository). Example: `[{ pattern: /^.attachments/, replacement: "file://some/conventional/folder/.attachments" }, { pattern: ^/, replacement: "{{BASEURL}}/"}]`
* `projectBaseUrl` the URL to use for `{{BASEURL}}` replacement
* `ignoreDisable` if this is `true` then disable comments are ignored.
* `retryOn429` if this is `true` then retry request when response is an HTTP code 429 after the duration indicated by `retry-after` header.
* `retryCount` the number of retries to be made on a 429 response. Default `2`.
* `fallbackRetryDelay` the delay in [zeit/ms](https://www.npmjs.com/package/ms) format. (e.g. `"2000ms"`, `20s`, `1m`) for retries on a 429 response when no `retry-after` header is returned or when it has an invalid value. Default is `60s`.
* `aliveStatusCodes` a list of HTTP codes to consider as alive.
Example: `[200,206]`
* `callback` function which accepts `(err, results)`.
* `err` an Error object when the operation cannot be completed, otherwise `null`.
* `results` an array of objects with the following properties:
* `link` the `link` provided as input
* `status` a string set to either `alive`, `ignored` or `dead`.
* `statusCode` the HTTP status code. Set to `0` if no HTTP status code was returned (e.g. when the server is down).
* `err` any connection error that occurred, otherwise `null`.
#### Disable comments
You can write html comments to disable markdown-link-check for parts of the text.
`<!-- markdown-link-check-disable -->` disables markdown link check.
`<!-- markdown-link-check-enable -->` reenables markdown link check.
`<!-- markdown-link-check-disable-next-line -->` disables markdown link check for the next line.
`<!-- markdown-link-check-disable-line -->` disables markdown link check for this line.
## Examples
### Module
**Basic usage:**
```js
'use strict';
var markdownLinkCheck = require('markdown-link-check');
markdownLinkCheck('[example](http://example.com)', function (err, results) {
if (err) {
console.error('Error', err);
return;
}
results.forEach(function (result) {
console.log('%s is %s', result.link, result.status);
});
});
```
**With options, for example using URL specific headers:**
```js
'use strict';
var markdownLinkCheck = require('markdown-link-check');
markdownLinkCheck('[example](http://example.com)', { httpHeaders: [{ urls: ['http://example.com'], headers: { 'Authorization': 'Basic Zm9vOmJhcg==' }}] }, function (err, results) {
if (err) {
console.error('Error', err);
return;
}
results.forEach(function (result) {
console.log('%s is %s', result.link, result.status);
});
});
```
### Command Line Tool
The command line tool optionally takes 1 argument, the file name or http/https URL.
If not supplied, the tool reads from standard input.
#### Check links from a markdown file hosted on the web
```shell
markdown-link-check https://github.com/tcort/markdown-link-check/blob/master/README.md
```
#### Check links from a local markdown file
```shell
markdown-link-check ./README.md
```
#### Check links from a local markdown folder (recursive)
Avoid using `find -exec` because it will swallow the error from each consecutive run.
Instead, use `xargs`:
```shell
find . -name \*.md -print0 | xargs -0 -n1 markdown-link-check
```
There is an [open issue](https://github.com/tcort/markdown-link-check/issues/78) for allowing the tool to specify
multiple files on the command line.
#### Usage
```shell
Usage: markdown-link-check [options] [filenameOrUrl]
Options:
-p, --progress show progress bar
-c, --config [config] apply a config file (JSON), holding e.g. url specific header configuration
-q, --quiet displays errors only
-v, --verbose displays detailed error information
-a, --alive <code> comma separated list of HTTP code to be considered as alive
-r, --retry retry after the duration indicated in 'retry-after' header when HTTP code is 429
-h, --help display help for command
-V, --version display version string (e.g. `1.2.3`)
```
##### Config file format
`config.json`:
* `ignorePatterns`: An array of objects holding regular expressions which a link is checked against and skipped for checking in case of a match.
* `replacementPatterns`: An array of objects holding regular expressions which are replaced in a link with their corresponding replacement string. This behavior allows (for example) to adapt to certain platform conventions hosting the Markdown. The special replacement `{{BASEURL}}` can be used to dynamically link to the current working directory (for example that `/` points to the root of your current working directory).
* `httpHeaders`: The headers are only applied to links where the link **starts with** one of the supplied URLs in the `urls` section.
* `timeout` timeout in [zeit/ms](https://www.npmjs.com/package/ms) format. (e.g. `"2000ms"`, `20s`, `1m`). Default `10s`.
* `retryOn429` if this is `true` then retry request when response is an HTTP code 429 after the duration indicated by `retry-after` header.
* `retryCount` the number of retries to be made on a 429 response. Default `2`.
* `fallbackRetryDelay` the delay in [zeit/ms](https://www.npmjs.com/package/ms) format. (e.g. `"2000ms"`, `20s`, `1m`) for retries on a 429 response when no `retry-after` header is returned or when it has an invalid value. Default is `60s`.
* `aliveStatusCodes` a list of HTTP codes to consider as alive.
**Example:**
```json
{
"ignorePatterns": [
{
"pattern": "^http://example.net"
}
],
"replacementPatterns": [
{
"pattern": "^.attachments",
"replacement": "file://some/conventional/folder/.attachments"
},
{
"pattern": "^/",
"replacement": "{{BASEURL}}/"
}
],
"httpHeaders": [
{
"urls": ["https://example.com"],
"headers": {
"Authorization": "Basic Zm9vOmJhcg==",
"Foo": "Bar"
}
}
],
"timeout": "20s",
"retryOn429": true,
"retryCount": 5,
"fallbackRetryDelay": "30s",
"aliveStatusCodes": [200, 206]
}
```
## Testing
```shell
npm test
```
## License
See [LICENSE.md](https://github.com/tcort/markdown-link-check/blob/master/LICENSE.md)