feat: add root_path config option (#14)

Fixes #12

.github/workflows/lint.yml

@@ -10,10 +10,10 @@ jobs:
   lint:
     runs-on: "ubuntu-latest"
     steps:
-      - uses: "actions/checkout@v4.1.7"
+      - uses: "actions/checkout@v4.2.2"
 
       - name: "Setup Node.js"
-        uses: "actions/setup-node@v4.0.3"
+        uses: "actions/setup-node@v4.1.0"
         with:
           node-version: "lts/*"
           cache: "npm"
@@ -30,6 +30,6 @@ jobs:
   commitlint:
     runs-on: "ubuntu-latest"
     steps:
-      - uses: "actions/checkout@v4.1.7"
+      - uses: "actions/checkout@v4.2.2"
 
-      - uses: "wagoid/commitlint-github-action@v6.1.2"
+      - uses: "wagoid/commitlint-github-action@v6.2.0"

.github/workflows/release.yml

@@ -13,13 +13,13 @@ jobs:
       pull-requests: "write"
       id-token: "write"
     steps:
-      - uses: "actions/checkout@v4.1.7"
+      - uses: "actions/checkout@v4.2.2"
         with:
           fetch-depth: 0
           persist-credentials: false
 
       - name: "Setup Node.js"
-        uses: "actions/setup-node@v4.0.3"
+        uses: "actions/setup-node@v4.1.0"
         with:
           node-version: "lts/*"
           cache: "npm"

.github/workflows/test.yml

@@ -10,10 +10,10 @@ jobs:
   test:
     runs-on: "ubuntu-latest"
     steps:
-      - uses: "actions/checkout@v4.1.7"
+      - uses: "actions/checkout@v4.2.2"
 
       - name: "Setup Node.js"
-        uses: "actions/setup-node@v4.0.3"
+        uses: "actions/setup-node@v4.1.0"
         with:
           node-version: "lts/*"
           cache: "npm"

.markdownlint-cli2.jsonc

@@ -1,11 +0,0 @@
-{
-  "config": {
-    "extends": "markdownlint/style/prettier",
-    "default": true,
-    "relative-links": true,
-    "no-inline-html": false,
-  },
-  "globs": ["**/*.md"],
-  "ignores": ["**/node_modules", "**/test/fixtures/**"],
-  "customRules": ["./src/index.js"],
-}

.markdownlint-cli2.mjs

@@ -0,0 +1,17 @@
+import relativeLinksRule from "./src/index.js"
+
+const config = {
+  config: {
+    extends: "markdownlint/style/prettier",
+    default: true,
+    "relative-links": {
+      root_path: ".",
+    },
+    "no-inline-html": false,
+  },
+  globs: ["**/*.md"],
+  ignores: ["**/node_modules", "**/test/fixtures/**"],
+  customRules: [relativeLinksRule],
+}
+
+export default config

CONTRIBUTING.md

@@ -4,7 +4,7 @@ Thanks a lot for your interest in contributing to **markdownlint-rule-relative-l
 
 ## Code of Conduct
 
-**markdownlint-rule-relative-links** adopted the [Contributor Covenant](https://www.contributor-covenant.org/) as its Code of Conduct, and we expect project participants to adhere to it. Please read [the full text](./CODE_OF_CONDUCT.md) so that you can understand what actions will and will not be tolerated.
+**markdownlint-rule-relative-links** adopted the [Contributor Covenant](https://www.contributor-covenant.org/) as its Code of Conduct, and we expect project participants to adhere to it. Please read [the full text](/CODE_OF_CONDUCT.md) so that you can understand what actions will and will not be tolerated.
 
 ## Open Development
 

README.md

@@ -51,12 +51,13 @@ awesome.md:3 relative-links Relative links should be valid ["./invalid.txt" shou
 - 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: `<a href="./link.txt" />` or `<img src="./image.png" />`).
 
-Contributions are welcome to improve the rule, and to alleviate these limitations. See [CONTRIBUTING.md](./CONTRIBUTING.md) for more information.
+Contributions are welcome to improve the rule, and to alleviate these limitations. See [CONTRIBUTING.md](/CONTRIBUTING.md) for more information.
 
 ### Related links
 
@@ -66,7 +67,7 @@ Contributions are welcome to improve the rule, and to alleviate these limitation
 
 ## Prerequisites
 
-[Node.js](https://nodejs.org/) >= 16.0.0
+[Node.js](https://nodejs.org/) >= 22.0.0
 
 ## Installation
 
@@ -80,18 +81,22 @@ There are various ways [markdownlint](https://github.com/DavidAnson/markdownlint
 
 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.jsonc`
+`.markdownlint-cli2.mjs`
 
-```json
+```js
-{
+import relativeLinksRule from "markdownlint-rule-relative-links"
-  "config": {
+
-    "default": true,
+const config = {
-    "relative-links": true
+  config: {
+    default: true,
+    "relative-links": true,
   },
-  "globs": ["**/*.md"],
+  globs: ["**/*.md"],
-  "ignores": ["**/node_modules"],
+  ignores: ["**/node_modules"],
-  "customRules": ["markdownlint-rule-relative-links"]
+  customRules: [relativeLinksRule],
 }
+
+export default config
 ```
 
 `package.json`
@@ -104,6 +109,25 @@ We recommend configuring [markdownlint-cli2](https://github.com/DavidAnson/markd
 }
 ```
 
+### 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
@@ -114,8 +138,8 @@ node --run lint:markdown
 
 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.
+The steps to contribute can be found in the [CONTRIBUTING.md](/CONTRIBUTING.md) file.
 
 ## 📄 License
 
-[MIT](./LICENSE)
+[MIT](/LICENSE)

package.json

@@ -18,6 +18,8 @@
     "markdownlint-rule"
   ],
   "main": "src/index.js",
+  "types": "src/index.d.ts",
+  "type": "module",
   "files": [
     "src"
   ],
@@ -26,7 +28,7 @@
     "provenance": true
   },
   "engines": {
-    "node": ">=16.0.0"
+    "node": ">=22.0.0"
   },
   "scripts": {
     "lint:editorconfig": "editorconfig-checker",
@@ -42,19 +44,19 @@
   },
   "devDependencies": {
     "@types/markdown-it": "14.1.2",
-    "@types/node": "22.9.0",
+    "@types/node": "22.15.17",
-    "editorconfig-checker": "6.0.0",
+    "editorconfig-checker": "6.0.1",
-    "eslint": "9.14.0",
+    "eslint": "9.26.0",
-    "eslint-config-conventions": "17.0.0",
+    "eslint-config-conventions": "19.2.0",
-    "eslint-plugin-promise": "7.1.0",
+    "eslint-plugin-promise": "7.2.1",
-    "eslint-plugin-unicorn": "56.0.0",
+    "eslint-plugin-unicorn": "59.0.1",
-    "eslint-plugin-import-x": "4.4.0",
+    "eslint-plugin-import-x": "4.11.1",
-    "globals": "15.12.0",
+    "globals": "16.1.0",
-    "markdownlint": "0.36.1",
+    "markdownlint": "0.38.0",
-    "markdownlint-cli2": "0.15.0",
+    "markdownlint-cli2": "0.18.0",
-    "prettier": "3.3.3",
+    "prettier": "3.5.3",
-    "semantic-release": "23.1.1",
+    "semantic-release": "24.2.3",
-    "typescript-eslint": "8.13.0",
+    "typescript-eslint": "8.32.0",
-    "typescript": "5.6.3"
+    "typescript": "5.8.3"
   }
 }

src/index.d.ts

@@ -0,0 +1,8 @@
+import type MarkdownIt from "markdown-it"
+import type { Rule } from "markdownlint"
+
+declare const relativeLinksRule: Rule
+export default relativeLinksRule
+
+declare const markdownIt: MarkdownIt
+export { markdownIt }

src/index.js

@@ -1,10 +1,8 @@
-"use strict"
+import { pathToFileURL } from "node:url"
+import fs from "node:fs"
 
-const { pathToFileURL } = require("node:url")
+import { filterTokens } from "./markdownlint-rule-helpers/helpers.js"
-const fs = require("node:fs")
+import {
-
-const { filterTokens } = require("./markdownlint-rule-helpers/helpers.js")
-const {
   convertHeadingToHTMLFragment,
   getMarkdownHeadings,
   getMarkdownIdOrAnchorNameFragments,
@@ -12,14 +10,16 @@ const {
   getNumberOfLines,
   getLineNumberStringFromFragment,
   lineFragmentRe,
-} = require("./utils.js")
+} from "./utils.js"
+
+export { markdownIt } from "./utils.js"
 
 /** @typedef {import('markdownlint').Rule} MarkdownLintRule */
 
 /**
  * @type {MarkdownLintRule}
  */
-const customRule = {
+const relativeLinksRule = {
   names: ["relative-links"],
   description: "Relative links should be valid",
   tags: ["links"],
@@ -51,17 +51,25 @@ const customRule = {
           }
         }
 
-        if (hrefSrc == null) {
+        if (hrefSrc == null || hrefSrc.startsWith("#")) {
           continue
         }
 
-        const url = new URL(hrefSrc, pathToFileURL(params.name))
+        let url
-        const isRelative =
-          url.protocol === "file:" &&
-          !hrefSrc.startsWith("/") &&
-          !hrefSrc.startsWith("#")
 
-        if (!isRelative) {
+        if (hrefSrc.startsWith("/")) {
+          const rootPath = params.config["root_path"]
+
+          if (!rootPath) {
+            continue
+          }
+
+          url = new URL(`.${hrefSrc}`, pathToFileURL(`${rootPath}/`))
+        } else {
+          url = new URL(hrefSrc, pathToFileURL(params.name))
+        }
+
+        if (url.protocol !== "file:") {
           continue
         }
 
@@ -172,4 +180,4 @@ const customRule = {
   },
 }
 
-module.exports = customRule
+export default relativeLinksRule

src/markdownlint-rule-helpers/helpers.js

@@ -14,7 +14,7 @@
  * @param {(token: MarkdownItToken) => void} handler Callback function.
  * @returns {void}
  */
-const filterTokens = (params, type, handler) => {
+export const filterTokens = (params, type, handler) => {
   for (const token of params.parsers.markdownit.tokens) {
     if (token.type === type) {
       handler(token)
@@ -28,11 +28,6 @@ const filterTokens = (params, type, handler) => {
  * @param {string} name HTML attribute name.
  * @returns {RegExp} Regular Expression for matching.
  */
-const getHtmlAttributeRe = (name) => {
+export const getHtmlAttributeRe = (name) => {
   return new RegExp(`\\s${name}\\s*=\\s*['"]?([^'"\\s>]*)`, "iu")
 }
-
-module.exports = {
-  filterTokens,
-  getHtmlAttributeRe,
-}

src/utils.js

@@ -1,10 +1,10 @@
-const MarkdownIt = require("markdown-it")
+import MarkdownIt from "markdown-it"
 
-const { getHtmlAttributeRe } = require("./markdownlint-rule-helpers/helpers.js")
+import { getHtmlAttributeRe } from "./markdownlint-rule-helpers/helpers.js"
 
-const markdownIt = new MarkdownIt({ html: true })
+export const markdownIt = new MarkdownIt({ html: true })
 
-const lineFragmentRe = /^#(?:L\d+(?:C\d+)?-L\d+(?:C\d+)?|L\d+)$/
+export const lineFragmentRe = /^#(?:L\d+(?:C\d+)?-L\d+(?:C\d+)?|L\d+)$/
 
 /**
  * Converts a Markdown heading into an HTML fragment according to the rules
@@ -14,7 +14,7 @@ const lineFragmentRe = /^#(?:L\d+(?:C\d+)?-L\d+(?:C\d+)?|L\d+)$/
  * @param {string} inlineText Inline token for heading.
  * @returns {string} Fragment string for heading.
  */
-const convertHeadingToHTMLFragment = (inlineText) => {
+export const convertHeadingToHTMLFragment = (inlineText) => {
   return (
     "#" +
     encodeURIComponent(
@@ -40,7 +40,7 @@ const ignoredTokens = new Set(["heading_open", "heading_close"])
  * @param {string} content
  * @returns {string[]}
  */
-const getMarkdownHeadings = (content) => {
+export const getMarkdownHeadings = (content) => {
   const tokens = markdownIt.parse(content, {})
 
   /** @type {string[]} */
@@ -88,7 +88,7 @@ const idHTMLAttributeRegex = getHtmlAttributeRe("id")
  * @param {string} content
  * @returns {string[]}
  */
-const getMarkdownIdOrAnchorNameFragments = (content) => {
+export const getMarkdownIdOrAnchorNameFragments = (content) => {
   const tokens = markdownIt.parse(content, {})
 
   /** @type {string[]} */
@@ -128,7 +128,7 @@ const getMarkdownIdOrAnchorNameFragments = (content) => {
  * @example isValidIntegerString("1abc") // false
  * @example isValidIntegerString("1.0") // false
  */
-const isValidIntegerString = (value) => {
+export const isValidIntegerString = (value) => {
   const regex = /^\d+$/
   return regex.test(value)
 }
@@ -138,7 +138,7 @@ const isValidIntegerString = (value) => {
  * @param {string} content
  * @returns {number}
  */
-const getNumberOfLines = (content) => {
+export const getNumberOfLines = (content) => {
   return content.split("\n").length
 }
 
@@ -148,16 +148,6 @@ const getNumberOfLines = (content) => {
  * @returns {string}
  * @example getLineNumberStringFromFragment("#L50") // 50
  */
-const getLineNumberStringFromFragment = (fragment) => {
+export const getLineNumberStringFromFragment = (fragment) => {
   return fragment.slice(2)
 }
-
-module.exports = {
-  lineFragmentRe,
-  convertHeadingToHTMLFragment,
-  getMarkdownHeadings,
-  getMarkdownIdOrAnchorNameFragments,
-  isValidIntegerString,
-  getNumberOfLines,
-  getLineNumberStringFromFragment,
-}

test/fixtures/config-dependent/absolute-paths.md

@@ -0,0 +1,3 @@
+# Valid
+
+![Absolute Path](/test/fixtures/image.png)

test/index.test.js

@@ -1,23 +1,31 @@
-const { test } = require("node:test")
+import { test } from "node:test"
-const assert = require("node:assert/strict")
+import assert from "node:assert/strict"
 
-const { markdownlint } = require("markdownlint").promises
+import * as markdownlint from "markdownlint/promise"
 
-const relativeLinksRule = require("../src/index.js")
+import relativeLinksRule, { markdownIt } from "../src/index.js"
+
+const defaultConfig = {
+  "relative-links": true,
+}
 
 /**
  *
  * @param {string} fixtureFile
+ * @param {Object} config
  * @returns
  */
-const validateMarkdownLint = async (fixtureFile) => {
+const validateMarkdownLint = async (fixtureFile, config = defaultConfig) => {
-  const lintResults = await markdownlint({
+  const lintResults = await markdownlint.lint({
     files: [fixtureFile],
     config: {
       default: false,
-      "relative-links": true,
+      ...config,
     },
     customRules: [relativeLinksRule],
+    markdownItFactory: () => {
+      return markdownIt
+    },
   })
   return lintResults[fixtureFile]
 }
@@ -143,11 +151,27 @@ test("ensure the rule validates correctly", async (t) => {
         fixturePath: "test/fixtures/invalid/non-existing-image.md",
         errors: ['"./image.png" should exist in the file system'],
       },
+      {
+        name: "should be invalid with incorrect absolute paths",
+        fixturePath: "test/fixtures/config-dependent/absolute-paths.md",
+        errors: ['"/test/fixtures/image.png" should exist in the file system'],
+        config: {
+          "relative-links": {
+            root_path: "test",
+          },
+        },
+      },
     ]
 
-    for (const { name, fixturePath, errors } of testCases) {
+    for (const {
+      name,
+      fixturePath,
+      errors,
+      config = defaultConfig,
+    } of testCases) {
       await t.test(name, async () => {
-        const lintResults = (await validateMarkdownLint(fixturePath)) ?? []
+        const lintResults =
+          (await validateMarkdownLint(fixturePath, config)) ?? []
         const errorsDetails = lintResults.map((result) => {
           assert.deepEqual(result.ruleNames, relativeLinksRule.names)
           assert.deepEqual(
@@ -216,7 +240,7 @@ test("ensure the rule validates correctly", async (t) => {
         fixturePath: "test/fixtures/valid/existing-image.md",
       },
       {
-        name: "should ignore absolute paths",
+        name: "should ignore absolute paths if root_path is not set",
         fixturePath: "test/fixtures/valid/ignore-absolute-paths.md",
       },
       {
@@ -228,11 +252,21 @@ test("ensure the rule validates correctly", async (t) => {
         fixturePath:
           "test/fixtures/valid/ignore-fragment-checking-in-own-file.md",
       },
+      {
+        name: "should be valid with correct absolute paths if root_path is set",
+        fixturePath: "test/fixtures/config-dependent/absolute-paths.md",
+        config: {
+          "relative-links": {
+            root_path: ".",
+          },
+        },
+      },
     ]
 
-    for (const { name, fixturePath } of testCases) {
+    for (const { name, fixturePath, config = defaultConfig } of testCases) {
       await t.test(name, async () => {
-        const lintResults = (await validateMarkdownLint(fixturePath)) ?? []
+        const lintResults =
+          (await validateMarkdownLint(fixturePath, config)) ?? []
         const errorsDetails = lintResults.map((result) => {
           return result.errorDetail
         })

test/utils.test.js

@@ -1,14 +1,14 @@
-const { test } = require("node:test")
+import { test } from "node:test"
-const assert = require("node:assert/strict")
+import assert from "node:assert/strict"
 
-const {
+import {
   convertHeadingToHTMLFragment,
   getMarkdownHeadings,
   getMarkdownIdOrAnchorNameFragments,
   isValidIntegerString,
   getNumberOfLines,
   getLineNumberStringFromFragment,
-} = require("../src/utils.js")
+} from "../src/utils.js"
 
 test("utils", async (t) => {
   await t.test("convertHeadingToHTMLFragment", async () => {