markdownlint-rule-relative-links

Custom rule for markdownlint to validate relative links.

CONTRIBUTING Licence MIT Contributor Covenant
Lint Test
Conventional Commits semantic-release npm version

## 📜 About **markdownlint-rule-relative-links** is a [markdownlint](https://github.com/DavidAnson/markdownlint) custom rule to validate relative links. It ensures that relative links (using `file:` protocol) are working and exists in the file system of the project that uses [markdownlint](https://github.com/DavidAnson/markdownlint). ### Example File structure: ```txt ├── abc.txt └── awesome.md ``` With `awesome.md` content: ```md [abc](./abc.txt) [Invalid link](./invalid.txt) ``` Running [markdownlint-cli2](https://github.com/DavidAnson/markdownlint-cli2) with `markdownlint-rule-relative-links` will output: ```sh awesome.md:3 relative-links Relative links should be valid ["./invalid.txt" should exist in the file system] ``` ### Additional features - Support images (e.g: `![Image](./image.png)`). - Support links fragments similar to the [built-in `markdownlint` rule - MD051](https://github.com/DavidAnson/markdownlint/blob/main/doc/md051.md) (e.g: `[Link](./awesome.md#heading)`). - Ignore external links and absolute paths as it only checks relative links (e.g: `https://example.com/` or `/absolute/path.png`). - If necessary, absolute paths can be validated too, with [`root_path` configuration option](#absolute-paths). ### Limitations - Only images and links defined using markdown syntax are validated, html syntax is ignored (e.g: `` or ``). Contributions are welcome to improve the rule, and to alleviate these limitations. See [CONTRIBUTING.md](/CONTRIBUTING.md) for more information. ### Related links - [DavidAnson/markdownlint#253](https://github.com/DavidAnson/markdownlint/issues/253) - [DavidAnson/markdownlint#121](https://github.com/DavidAnson/markdownlint/issues/121) - [nschonni/markdownlint-valid-links](https://github.com/nschonni/markdownlint-valid-links) ## Prerequisites [Node.js](https://nodejs.org/) >= 22.0.0 ## Installation ```sh npm install --save-dev markdownlint-rule-relative-links ``` ## Configuration There are various ways [markdownlint](https://github.com/DavidAnson/markdownlint) can be configured using objects, config files etc. For more information on configuration refer to [options.config](https://github.com/DavidAnson/markdownlint#optionsconfig). We recommend configuring [markdownlint-cli2](https://github.com/DavidAnson/markdownlint-cli2) over [markdownlint-cli](https://github.com/igorshubovych/markdownlint-cli) for compatibility with the [vscode-markdownlint](https://github.com/DavidAnson/vscode-markdownlint) extension. `.markdownlint-cli2.mjs` ```js import relativeLinksRule from "markdownlint-rule-relative-links" const config = { config: { default: true, "relative-links": true, }, globs: ["**/*.md"], ignores: ["**/node_modules"], customRules: [relativeLinksRule], } export default config ``` `package.json` ```json { "scripts": { "lint:markdown": "markdownlint-cli2" } } ``` ### Absolute paths GitHub (and, likely, other similar platforms) resolves absolute paths in Markdown links relative to the repository root. To validate such links, add `root_path` option to the configuration: ```js config: { default: true, "relative-links": { root_path: ".", }, }, ``` After this change, all absolute paths will be converted to relative paths, and will be resolved relative to the specified directory. For example, if you run markdownlint from a subdirectory (if `package.json` is located in a subdirectory), you should set `root_path` to `".."`. ## Usage ```sh node --run lint:markdown ``` ## 💡 Contributing Anyone can help to improve the project, submit a Feature Request, a bug report or even correct a simple spelling mistake. The steps to contribute can be found in the [CONTRIBUTING.md](/CONTRIBUTING.md) file. ## 📄 License [MIT](/LICENSE)