markdownlint-rule-relative-links

markdownlint-rule-relative-links

Custom rule for markdownlint to validate relative links.

📜 About

markdownlint-rule-relative-links is a 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.

Example

File structure:

├── abc.txt
└── awesome.md

With awesome.md content:

[abc](./abc.txt)

[Invalid link](./invalid.txt)

Running markdownlint-cli2 with markdownlint-rule-relative-links will output:

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 (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.

Limitations

• Only images and links defined using markdown syntax are validated, html syntax is ignored (e.g: <a href="./link.txt" /> or <img src="./image.png" />).

Contributions are welcome to improve the rule, and to alleviate these limitations. See CONTRIBUTING.md for more information.

Related links

• DavidAnson/markdownlint#253
• DavidAnson/markdownlint#121
• nschonni/markdownlint-valid-links

Prerequisites

Node.js >= 22.0.0

Installation

npm install --save-dev markdownlint-rule-relative-links

Configuration

There are various ways markdownlint can be configured using objects, config files etc. For more information on configuration refer to options.config.

We recommend configuring markdownlint-cli2 over markdownlint-cli for compatibility with the vscode-markdownlint extension.

.markdownlint-cli2.mjs

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

{
  "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:

  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

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 file.

📄 License

MIT