readme.md

remark-lint-no-dead-urls

remark-lint rule to warn when URLs are dead.

Contents

• What is this?
• When should I use this?
• Install
• Use
• API
  • Options
  • unified().use(remarkLintNoDeadUrls[, options])
• Related
• Compatibility
• Security
• Contribute
• License

What is this?

This lint rule checks whether URLs are alive or not.

When should I use this?

You can use this lint rule to check that URLs are alive.

It’s similar to remark-validate-links, but there’s an important difference. That package checks the file system locally: whether path/to/example.md exists. But this package, remark-lint-no-dead-urls, checks the internet: whether https://a.com is alive, /docs/example is reachable on https://mydomain.com, and even whether certain IDs exist on a web page.

This package uses dead-or-alive. You can use it when you want to check URLs programmatically yourself.

Install

This package is ESM only. In Node.js (version 18+), install with npm:

npm install remark-lint-no-dead-urls

In Deno with esm.sh:

import remarkLintNoDeadUrls from 'https://esm.sh/remark-lint-no-dead-urls@2'

In browsers with esm.sh:

<script type="module">
  import remarkLintNoDeadUrls from 'https://esm.sh/remark-lint-no-dead-urls@2?bundle'
</script>

Use

On the API:

import remarkLintNoDeadUrls from 'remark-lint-no-dead-urls'
import remarkLint from 'remark-lint'
import remarkParse from 'remark-parse'
import remarkStringify from 'remark-stringify'
import {read} from 'to-vfile'
import {unified} from 'unified'
import {reporter} from 'vfile-reporter'

const file = await read('example.md')

await unified()
  .use(remarkParse)
  .use(remarkLint)
  .use(remarkLintNoDeadUrls)
  .use(remarkStringify)
  .process(file)

console.error(reporter(file))

On the CLI:

remark --frail --use remark-lint --use remark-lint-no-dead-urls .

On the CLI in a config file (here a package.json):

 …
 "remarkConfig": {
   "plugins": [
     …
     "remark-lint",
+    "remark-lint-no-dead-urls",
     …
   ]
 }
 …

API

This package exports no identifiers. It exports the additional TypeScript type Options. The default export is remarkLintNoDeadUrls.

Options

Configuration (TypeScript type).

Fields

• deadOrAliveOptions (Options from dead-or-alive, optional) — options passed to dead-or-alive; deadOrAliveOptions.findUrls is always off as further URLs are not applicable
• from (string, optional, example: 'https://example.com/from') — check relative values relative to this URL; you can also define this by setting origin and pathname in file.data.meta
• skipLocalhost (boolean, default: false) — whether to ignore localhost links such as http://localhost/*, http://127.0.0.1/*; shortcut for a skip pattern of /^(https?:\/\/)(localhost|127\.0\.0\.1)(:\d+)?/
• skipOffline (boolean, default: false) — whether to let offline runs pass quietly
• skipUrlPatterns (Array<RegExp | string>, optional) — list of patterns for URLs that should be skipped; each URL will be tested against each pattern and will be ignored if new RegExp(pattern).test(url) === true

unified().use(remarkLintNoDeadUrls[, options])

Warn when URLs are dead.

Notes

To improve performance, decrease maxRetries in deadOrAliveOptions and/or decrease the value used for sleep in deadOrAliveOptions. The normal behavior is to assume connections might be flakey and to sleep a while and retry a couple times.

If you do not care whether anchors exist and don’t need to support HTML redirects, you can pass checkAnchor: false and followMetaHttpEquiv: false in deadOrAliveOptions, which enables a fast path without parsing HTML.

Parameters

• options (Options, optional) — configuration

Returns

Transform ((tree: Root, file: VFile) => Promise<Root>).

Related

• remark-lint — markdown code style linter
• remark-validate-links — ensure local links work

Compatibility

This projects is compatible with maintained versions of Node.js.

When we cut a new major release, we drop support for unmaintained versions of Node. This means we try to keep the current release line, remark-lint-no-dead-urls@2, compatible with Node.js 18.

Security

This package can typically be considered safe. Note that this package checks URLs over the internet. Don’t use this if you consider that’s dangerous.

Contribute

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.

License

MIT © David Clark