feat: add config-option for fragment-index-divider (#20)

.oxlintrc.json

@@ -1,4 +1,10 @@
 {
   "$schema": "./node_modules/oxlint/configuration_schema.json",
-  "extends": ["node_modules/eslint-config-conventions/.oxlintrc.json"]
+  "extends": ["node_modules/eslint-config-conventions/.oxlintrc.json"],
+  "env": {
+    "builtin": true,
+    "browser": true,
+    "node": true,
+    "shared-node-browser": true
+  }
 }

README.md

@@ -52,6 +52,8 @@ awesome.md:3 relative-links Relative links should be valid ["./invalid.txt" shou
 - 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).
+- Headings defined multiple times in one file, will get enumerated as `<heading><divider><count>`.
+  The divier can be customized with [`fragment-count-divider`](#divider-for-fragment-index).
 
 ### Limitations
 
@@ -128,6 +130,16 @@ After this change, all absolute paths will be converted to relative paths, and w
 
 For example, if you run markdownlint from a subdirectory (if `package.json` is located in a subdirectory), you should set `root_path` to `".."`.
 
+### Divider for Fragment-Index
+
+Headers with the same name in the same file, are appended with their index when converting them to the fragment.
+Between the original fragment and the index a divider will be inserted.
+The final fragment is `<original-fragment><divider><index>`.
+
+This divider can be configured with `fragment-index-divider` to accomodate different markdown-engines.
+
+The default-value is `-`.
+
 ## Usage
 
 ```sh

package.json

@@ -36,18 +36,18 @@
     "release": "semantic-release"
   },
   "dependencies": {
-    "markdown-it": "14.1.0",
+    "markdown-it": "14.1.1",
     "mime": "4.1.0"
   },
   "devDependencies": {
     "@types/markdown-it": "14.1.2",
-    "@types/node": "25.2.1",
-    "eslint-config-conventions": "21.2.0",
+    "@types/node": "25.3.0",
+    "eslint-config-conventions": "21.2.2",
     "markdownlint": "0.40.0",
-    "markdownlint-cli2": "0.20.0",
-    "oxfmt": "0.28.0",
-    "oxlint": "1.43.0",
-    "oxlint-tsgolint": "0.11.4",
+    "markdownlint-cli2": "0.21.0",
+    "oxfmt": "0.34.0",
+    "oxlint": "1.49.0",
+    "oxlint-tsgolint": "0.14.1",
     "semantic-release": "25.0.3",
     "typescript": "5.9.3"
   },

src/index.js

@@ -144,12 +144,14 @@ const relativeLinksRule = {
         /** @type {Map<string, number>} */
         const fragments = new Map()
 
+        const fragmentCountDivider = params.config["fragment-index-divider"] ?? "-"
+
         const fragmentsHTML = headings.map((heading) => {
           const fragment = convertHeadingToHTMLFragment(heading)
           const count = fragments.get(fragment) ?? 0
           fragments.set(fragment, count + 1)
           if (count !== 0) {
-            return `${fragment}-${count}`
+            return `${fragment}${fragmentCountDivider}${count}`
           }
           return fragment
         })

test/fixtures/valid/existing-heading-fragment-divider/awesome.md

@@ -0,0 +1,13 @@
+# Awesome
+
+## Existing Heading
+
+### Repeated Heading
+
+Text
+
+### Repeated Heading
+
+Text
+
+### Repeated Heading

test/fixtures/valid/existing-heading-fragment-divider/existing-heading-fragment.md

@@ -0,0 +1,9 @@
+# Valid
+
+[Link fragment](./awesome.md#existing-heading)
+
+[Link fragment Repeated 0](./awesome.md#repeated-heading)
+
+[Link fragment Repeated 1](./awesome.md#repeated-heading_1)
+
+[Link fragment Repeated 2](./awesome.md#repeated-heading_2)

test/index.test.js

@@ -239,6 +239,16 @@ test("ensure the rule validates correctly", async (t) => {
           },
         },
       },
+      {
+        name: "should be valid with multiple existing element id fragments",
+        fixturePath:
+          "test/fixtures/valid/existing-heading-fragment-divider/existing-heading-fragment.md",
+        config: {
+          "relative-links": {
+            "fragment-index-divider": "_",
+          },
+        },
+      },
       {
         name: "should ignore external image links",
         fixturePath: "test/fixtures/valid/ignore-external-image.md",