ci: pin GitHub Actions by commit-hash

Ref: https://blog.rafaelgss.dev/why-you-should-pin-actions-by-commit-hash

.github/workflows/lint.yml

@@ -10,10 +10,10 @@ jobs:
   lint:
     runs-on: "ubuntu-latest"
     steps:
-      - uses: "actions/checkout@v4.2.2"
+      - uses: "actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8" # v5.0.0
 
       - name: "Setup Node.js"
-        uses: "actions/setup-node@v4.1.0"
+        uses: "actions/setup-node@2028fbc5c25fe9cf00d9f06a71cc4710d4507903" # v6.0.0
         with:
           node-version: "lts/*"
           cache: "npm"
@@ -30,6 +30,6 @@ jobs:
   commitlint:
     runs-on: "ubuntu-latest"
     steps:
-      - uses: "actions/checkout@v4.2.2"
+      - uses: "actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8" # v5.0.0
 
-      - uses: "wagoid/commitlint-github-action@v6.2.0"
+      - uses: "wagoid/commitlint-github-action@b948419dd99f3fd78a6548d48f94e3df7f6bf3ed" # v6.2.1

.github/workflows/release.yml

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

.github/workflows/test.yml

@@ -8,12 +8,19 @@ on:
 
 jobs:
   test:
-    runs-on: "ubuntu-latest"
+    strategy:
+      fail-fast: false
+      matrix:
+        runs-on:
+          - "ubuntu-latest"
+          - "windows-latest"
+          - "macos-latest"
+    runs-on: "${{ matrix.runs-on }}"
     steps:
-      - uses: "actions/checkout@v4.2.2"
+      - uses: "actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8" # v5.0.0
 
       - name: "Setup Node.js"
-        uses: "actions/setup-node@v4.1.0"
+        uses: "actions/setup-node@2028fbc5c25fe9cf00d9f06a71cc4710d4507903" # v6.0.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
 
@@ -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
-{
-  "config": {
-    "default": true,
-    "relative-links": true
+```js
+import relativeLinksRule from "markdownlint-rule-relative-links"
+
+const config = {
+  config: {
+    default: true,
+    "relative-links": true,
   },
-  "globs": ["**/*.md"],
-  "ignores": ["**/node_modules"],
-  "customRules": ["markdownlint-rule-relative-links"]
+  globs: ["**/*.md"],
+  ignores: ["**/node_modules"],
+  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

@@ -44,19 +44,19 @@
   },
   "devDependencies": {
     "@types/markdown-it": "14.1.2",
-    "@types/node": "22.10.2",
-    "editorconfig-checker": "6.0.0",
-    "eslint": "9.17.0",
-    "eslint-config-conventions": "18.0.0",
+    "@types/node": "24.9.2",
+    "editorconfig-checker": "6.1.1",
+    "eslint": "9.39.0",
+    "eslint-config-conventions": "21.1.0",
     "eslint-plugin-promise": "7.2.1",
-    "eslint-plugin-unicorn": "56.0.1",
-    "eslint-plugin-import-x": "4.6.1",
-    "globals": "15.14.0",
-    "markdownlint": "0.37.2",
-    "markdownlint-cli2": "0.17.0",
-    "prettier": "3.4.2",
-    "semantic-release": "24.2.0",
-    "typescript-eslint": "8.18.2",
-    "typescript": "5.7.2"
+    "eslint-plugin-unicorn": "62.0.0",
+    "eslint-plugin-import-x": "4.16.1",
+    "globals": "16.4.0",
+    "markdownlint": "0.38.0",
+    "markdownlint-cli2": "0.18.1",
+    "prettier": "3.6.2",
+    "semantic-release": "25.0.1",
+    "typescript-eslint": "8.46.2",
+    "typescript": "5.9.3"
   }
 }

src/index.d.ts

@@ -1,5 +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

@@ -12,6 +12,8 @@ import {
   lineFragmentRe,
 } from "./utils.js"
 
+export { markdownIt } from "./utils.js"
+
 /** @typedef {import('markdownlint').Rule} MarkdownLintRule */
 
 /**
@@ -49,17 +51,25 @@ const relativeLinksRule = {
           }
         }
 
-        if (hrefSrc == null) {
+        if (hrefSrc == null || hrefSrc.startsWith("#")) {
           continue
         }
 
-        const url = new URL(hrefSrc, pathToFileURL(params.name))
-        const isRelative =
-          url.protocol === "file:" &&
-          !hrefSrc.startsWith("/") &&
-          !hrefSrc.startsWith("#")
+        let url
 
-        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
         }
 

src/utils.js

@@ -2,7 +2,7 @@ import MarkdownIt from "markdown-it"
 
 import { getHtmlAttributeRe } from "./markdownlint-rule-helpers/helpers.js"
 
-const markdownIt = new MarkdownIt({ html: true })
+export const markdownIt = new MarkdownIt({ html: true })
 
 export const lineFragmentRe = /^#(?:L\d+(?:C\d+)?-L\d+(?:C\d+)?|L\d+)$/
 

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

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

test/index.test.js

@@ -3,21 +3,29 @@ import assert from "node:assert/strict"
 
 import * as markdownlint from "markdownlint/promise"
 
-import relativeLinksRule from "../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.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
         })