{"id":28573669,"url":"https://github.com/remarkjs/remark-validate-links","last_synced_at":"2025-06-10T21:19:22.156Z","repository":{"id":40697922,"uuid":"39290856","full_name":"remarkjs/remark-validate-links","owner":"remarkjs","description":"plugin to check that markdown links and images reference existing files and headings","archived":false,"fork":false,"pushed_at":"2025-02-21T14:35:07.000Z","size":582,"stargazers_count":115,"open_issues_count":0,"forks_count":26,"subscribers_count":10,"default_branch":"main","last_synced_at":"2025-06-01T06:23:14.675Z","etag":null,"topics":["link","markdown","remark","remark-plugin","valid"],"latest_commit_sha":null,"homepage":"https://remark.js.org","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/remarkjs.png","metadata":{"files":{"readme":"readme.md","changelog":null,"contributing":null,"funding":null,"license":"license","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":"unifiedjs","open_collective":"unified"}},"created_at":"2015-07-18T07:43:35.000Z","updated_at":"2025-05-24T10:42:46.000Z","dependencies_parsed_at":"2024-06-18T12:38:49.206Z","dependency_job_id":"03dc08f1-0f5a-4b59-aa49-de55ac3f1fe6","html_url":"https://github.com/remarkjs/remark-validate-links","commit_stats":{"total_commits":230,"total_committers":14,"mean_commits":"16.428571428571427","dds":0.07391304347826089,"last_synced_commit":"ac9a800fb106f46db63b0aa2db7431845ae916ff"},"previous_names":["wooorm/mdast-validate-links"],"tags_count":43,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/remarkjs%2Fremark-validate-links","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/remarkjs%2Fremark-validate-links/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/remarkjs%2Fremark-validate-links/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/remarkjs%2Fremark-validate-links/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/remarkjs","download_url":"https://codeload.github.com/remarkjs/remark-validate-links/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/remarkjs%2Fremark-validate-links/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":258798851,"owners_count":22759743,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["link","markdown","remark","remark-plugin","valid"],"created_at":"2025-06-10T21:18:59.059Z","updated_at":"2025-06-10T21:19:21.570Z","avatar_url":"https://github.com/remarkjs.png","language":"JavaScript","funding_links":["https://github.com/sponsors/unifiedjs","https://opencollective.com/unified"],"categories":[],"sub_categories":[],"readme":"# remark-validate-links\n\n[![Build][badge-build-image]][badge-build-url]\n[![Coverage][badge-coverage-image]][badge-coverage-url]\n[![Downloads][badge-downloads-image]][badge-downloads-url]\n[![Size][badge-size-image]][badge-size-url]\n\n**[remark][github-remark]** plugin to check that markdown links and images\npoint to existing local files and headings in a Git repo.\n\nFor example,\nthis document does not have a heading named `Hello`.\nSo if we’d link to that heading (`[welcome](#hello)`),\nwe’d get a warning.\nLinks to headings in other markdown documents (`examples/foo.md#hello`) and\nlinks to files (`license` or `index.js`) are also checked.\n\nThis is specifically for Git repos.\nLike this one.\nNot for say a website.\n\n## Contents\n\n* [What is this?](#what-is-this)\n* [When should I use this?](#when-should-i-use-this)\n* [Install](#install)\n* [Use](#use)\n* [API](#api)\n  * [`unified().use(remarkValidateLinks[, options])`](#unifieduseremarkvalidatelinks-options)\n  * [`Options`](#options)\n  * [`UrlConfig`](#urlconfig)\n* [Examples](#examples)\n  * [Example: CLI](#example-cli)\n  * [Example: CLI in npm scripts](#example-cli-in-npm-scripts)\n* [Integration](#integration)\n* [Compatibility](#compatibility)\n* [Security](#security)\n* [Related](#related)\n* [Contribute](#contribute)\n* [License](#license)\n\n## What is this?\n\nThis package is a [unified][github-unified] ([remark][github-remark])\nplugin to check local links in a Git repo.\n\n## When should I use this?\n\nThis project is useful if you have a Git repo,\nsuch as this one,\nwith docs in markdown and links to headings and other files,\nand want to check whether they’re correct.\nCompared to other links checkers,\nthis project can work offline\n(making this plugin fast en prone to fewer false positives),\nand is specifically made for local links in Git repos.\nThis plugin does not check external URLs\n(see [`remark-lint-no-dead-urls`][github-remark-lint-no-dead-urls])\nor undefined references (see\n[`remark-lint-no-undefined-references`][github-remark-lint-undefined]).\n\n## Install\n\nThis package is [ESM only][github-gist-esm].\nIn Node.js (version 16+),\ninstall with [npm][npmjs-install]:\n\n```sh\nnpm install remark-validate-links\n```\n\nIn Deno with [`esm.sh`][esmsh]:\n\n```js\nimport remarkValidateLinks from 'https://esm.sh/remark-validate-links@13'\n```\n\nIn browsers with [`esm.sh`][esmsh]:\n\n```html\n\u003cscript type=\"module\"\u003e\n  import remarkValidateLinks from 'https://esm.sh/remark-validate-links@13?bundle'\n\u003c/script\u003e\n```\n\n## Use\n\nSay we have the following file `example.md` in this project:\n\n```markdown\n# Alpha\n\nLinks are checked:\n\nThis [exists](#alpha).\nThis [one does not](#apha).\n\n# Bravo\n\nHeadings in `readme.md` are [checked](readme.md#no-such-heading).\nAnd [missing files are reported](missing-example.js).\n\nDefinitions are also checked:\n\n[alpha]: #alpha\n[charlie]: #charlie\n\nReferences w/o definitions are not checked: [delta]\n```\n\n…and a module `example.js`:\n\n```js\nimport remarkValidateLinks from 'remark-validate-links'\nimport {remark} from 'remark'\nimport {read} from 'to-vfile'\nimport {reporter} from 'vfile-reporter'\n\nconst file = await remark()\n  .use(remarkValidateLinks)\n  .process(await read('example.md'))\n\nconsole.log(reporter(file))\n```\n\n…then running `node example.js` yields:\n\n```markdown\nexample.md\n6:6-6:27   warning Cannot find heading for `#apha`; did you mean `alpha` missing-heading remark-validate-links:missing-heading\n11:5-11:53 warning Cannot find file `missing-example.js`                 missing-file    remark-validate-links:missing-file\n16:1-16:20 warning Cannot find heading for `#charlie`                    missing-heading remark-validate-links:missing-heading\n\n⚠ 3 warnings\n```\n\n\u003e 👉 **Note**:\n\u003e `readme.md#no-such-heading` is not warned about on the API,\n\u003e as the API does not check headings in other markdown files;\n\u003e the remark CLI is able to do that.\n\n## API\n\nThis package exports no identifiers.\nThe default export is [`remarkValidateLinks`][api-remark-validate-links].\nIt exports the [TypeScript][] types\n[`Options`][api-options]\nand\n[`UrlConfig`][api-url-config].\n\n### `unified().use(remarkValidateLinks[, options])`\n\nCheck that markdown links and images point to existing local files and headings\nin a Git repo.\n\n\u003e ⚠️ **Important**:\n\u003e the API in Node.js checks links to headings and files but does not check\n\u003e whether headings in other files exist;\n\u003e the API in browsers only checks links to headings in the same file;\n\u003e the CLI can check everything.\n\n###### Parameters\n\n* `options` ([`Options`][api-options], optional)\n  — configuration\n\n###### Returns\n\nTransform ([`Transformer`][github-unified-transformer]).\n\n### `Options`\n\nConfiguration (TypeScript type).\n\n###### Fields\n\n* `repository`\n  (`string` or `false`, default: detected from Git remote)\n  — URL to hosted Git;\n  if you’re not in a Git repository,\n  you must pass `false`;\n  if the repository resolves to something npm understands as a Git host such\n  as GitHub, GitLab, or Bitbucket,\n  then full URLs to that host\n  (say,\n  `https://github.com/remarkjs/remark-validate-links/readme.md#install`)\n  are checked\n* `root`\n  (`string`, default: local Git folder)\n  — path to Git root folder;\n  if both `root` and `repository` are nullish,\n  the Git root is detected;\n  if `root` is not given but `repository` is,\n  `file.cwd` is used\n* `skipPathPatterns`\n  (`Array\u003cRegExp | string\u003e`, optional)\n  — list of patterns for *paths* that should be skipped;\n  each absolute local path + hash will be tested against each pattern and\n  will be ignored if `new RegExp(pattern).test(value) === true`;\n  example value are then `/Users/tilde/path/to/repo/readme.md#some-heading`.\n* `urlConfig`\n  ([`UrlConfig`][api-url-config], default: detected from repo)\n  — config on how hosted Git works;\n  `github.com`, `gitlab.com`, or `bitbucket.org`\n  work automatically;\n  otherwise,\n  pass `urlConfig` manually\n\n### `UrlConfig`\n\nHosted Git info (TypeScript type).\n\n###### Fields\n\n* `headingPrefix`\n  (`string`, optional, example: `'#'`, `'#markdown-header-'`)\n  — prefix of headings\n* `hostname`\n  (`string`, optional, example: `'github.com'`,\n  `'bitbucket.org'`)\n  — domain of URLs\n* `lines`\n  (`boolean`, default: `false`)\n  — whether lines in files can be linked\n* `path`\n  (`string`, optional, example:\n  `'/remarkjs/remark-validate-links/blob/'`,\n  `'/remarkjs/remark-validate-links/src/'`)\n  — path prefix before files\n* `topAnchor`\n  (`string`, optional, example: `#readme`)\n  — hash to top of readme\n\n###### Notes\n\nFor this repository (`remarkjs/remark-validate-links` on GitHub) `urlConfig`\nlooks as follows:\n\n```js\n{\n  // Prefix of headings:\n  headingPrefix: '#',\n  // Domain of URLs:\n  hostname: 'github.com',\n  // Whether lines in files can be linked:\n  lines: true,\n  // Path prefix before files:\n  prefix: '/remarkjs/remark-validate-links/blob/',\n  // Hash to top of markdown documents:\n  topAnchor: '#readme'\n}\n```\n\nIf this project were hosted on Bitbucket,\nthe config would be:\n\n```js\n{\n  headingPrefix: '#markdown-header-',\n  hostname: 'bitbucket.org',\n  lines: false,\n  prefix: '/remarkjs/remark-validate-links/src/'\n}\n```\n\n## Examples\n\n### Example: CLI\n\nIt’s recommended to use `remark-validate-links` on the CLI with\n[`remark-cli`][github-remark-cli].\nInstall both with [npm][npmjs-install]:\n\n```sh\nnpm install remark-cli remark-validate-links --save-dev\n```\n\nLet’s say we have a `readme.md` (this current document) and an `example.md`\nwith the following text:\n\n```markdown\n# Hello\n\nRead more [whoops, this does not exist](#world).\n\nThis doesn’t exist either [whoops!](readme.md#foo).\n\nBut this does exist: [license](license).\n\nSo does this: [readme](readme.md#install).\n```\n\nNow,\nrunning `./node_modules/.bin/remark --use remark-validate-links .` yields:\n\n\u003c!-- To do: regenerate. --\u003e\n\n```text\nexample.md\n  3:11-3:48  warning  Link to unknown heading: `world`               missing-heading          remark-validate-links\n  5:27-5:51  warning  Link to unknown heading in `readme.md`: `foo`  missing-heading-in-file  remark-validate-links\n\nreadme.md: no issues found\n\n⚠ 2 warnings\n```\n\n### Example: CLI in npm scripts\n\nYou can use `remark-validate-links` and [`remark-cli`][github-remark-cli] in\nan npm script to check and format markdown in your project.\nInstall both with [npm][npmjs-install]:\n\n```sh\nnpm install remark-cli remark-validate-links --save-dev\n```\n\nThen,\nadd a format script and configuration to `package.json`:\n\n```js\n{\n  // …\n  \"scripts\": {\n    // …\n    \"format\": \"remark . --quiet --frail --output\",\n    // …\n  },\n  \"remarkConfig\": {\n    \"plugins\": [\n      \"remark-validate-links\"\n    ]\n  },\n  // …\n}\n```\n\n\u003e 💡 **Tip**:\n\u003e add other tools such as prettier or ESLint to check and format other files.\n\n\u003e 💡 **Tip**:\n\u003e run `./node_modules/.bin/remark --help` for help with `remark-cli`.\n\nNow you check and format markdown in your project with:\n\n```sh\nnpm run format\n```\n\n## Integration\n\n`remark-validate-links` can detect anchors on nodes through several properties\non nodes:\n\n* `node.data.hProperties.name`\n  — used by\n  [`mdast-util-to-hast`][github-mdast-util-to-hast-notes]\n  to create a `name` attribute,\n  which anchors can link to\n* `node.data.hProperties.id`\n  — used by\n  [`mdast-util-to-hast`][github-mdast-util-to-hast-notes]\n  to create an `id` attribute,\n  which anchors can link to\n* `node.data.id`\n  — used potentially in the future by other tools to signal unique identifiers\n  on nodes\n\n## Compatibility\n\nProjects maintained by the unified collective are compatible with maintained\nversions of Node.js.\n\nWhen we cut a new major release,\nwe drop support for unmaintained versions of Node.\nThis means we try to keep the current release line,\n`remark-validate-links@13`,\ncompatible with Node.js 16.\n\nThis plugin works with `unified` version 6+,\n`remark` version 7+,\nand `remark-cli` version 8+.\n\n## Security\n\n`remark-validate-links`,\nin Node,\naccesses the file system based on user content,\nand this may be dangerous.\nIn Node `git remote` and `git rev-parse` also runs for processed files.\n\nThe tree is not modified,\nso there are no openings for [cross-site scripting (XSS)][wikipedia-xss]\nattacks.\n\n## Related\n\n* [`remark-lint`][github-remark-lint]\n  — markdown code style linter\n* [`remark-lint-no-dead-urls`][github-remark-lint-no-dead-urls]\n  — check that external links are alive\n\n## Contribute\n\nSee [`contributing.md`][health-contributing]\nin\n[`remarkjs/.github`][health]\nfor ways to get started.\nSee [`support.md`][health-support] for ways to get help.\n\nThis project has a [code of conduct][health-coc].\nBy interacting with this repository,\norganization,\nor community you agree to abide by its terms.\n\n## License\n\n[MIT][file-license] © [Titus Wormer][wooorm]\n\n\u003c!-- Definitions --\u003e\n\n[api-options]: #options\n\n[api-remark-validate-links]: #unifieduseremarkvalidatelinks-options\n\n[api-url-config]: #urlconfig\n\n[badge-build-image]: https://github.com/remarkjs/remark-validate-links/workflows/main/badge.svg\n\n[badge-build-url]: https://github.com/remarkjs/remark-validate-links/actions\n\n[badge-coverage-image]: https://img.shields.io/codecov/c/github/remarkjs/remark-validate-links.svg\n\n[badge-coverage-url]: https://codecov.io/github/remarkjs/remark-validate-links\n\n[badge-downloads-image]: https://img.shields.io/npm/dm/remark-validate-links.svg\n\n[badge-downloads-url]: https://www.npmjs.com/package/remark-validate-links\n\n[badge-size-image]: https://img.shields.io/bundlejs/size/remark-validate-links\n\n[badge-size-url]: https://bundlejs.com/?q=remark-validate-links\n\n[esmsh]: https://esm.sh\n\n[file-license]: license\n\n[github-gist-esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c\n\n[github-mdast-util-to-hast-notes]: https://github.com/syntax-tree/mdast-util-to-hast#notes\n\n[github-remark]: https://github.com/remarkjs/remark\n\n[github-remark-cli]: https://github.com/remarkjs/remark/tree/main/packages/remark-cli#readme\n\n[github-remark-lint]: https://github.com/remarkjs/remark-lint\n\n[github-remark-lint-no-dead-urls]: https://github.com/remarkjs/remark-lint-no-dead-urls\n\n[github-remark-lint-undefined]: https://github.com/remarkjs/remark-lint/tree/master/packages/remark-lint-no-undefined-references\n\n[github-unified]: https://github.com/unifiedjs/unified\n\n[github-unified-transformer]: https://github.com/unifiedjs/unified#transformer\n\n[health]: https://github.com/remarkjs/.github\n\n[health-coc]: https://github.com/remarkjs/.github/blob/main/code-of-conduct.md\n\n[health-contributing]: https://github.com/remarkjs/.github/blob/main/contributing.md\n\n[health-support]: https://github.com/remarkjs/.github/blob/main/support.md\n\n[npmjs-install]: https://docs.npmjs.com/cli/install\n\n[typescript]: https://www.typescriptlang.org\n\n[wikipedia-xss]: https://en.wikipedia.org/wiki/Cross-site_scripting\n\n[wooorm]: https://wooorm.com\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fremarkjs%2Fremark-validate-links","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fremarkjs%2Fremark-validate-links","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fremarkjs%2Fremark-validate-links/lists"}