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

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

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",