Fix #672: Prevent duplicate heading IDs in Docusaurus

.markdownlint-cli2.jsonc

@@ -0,0 +1,20 @@
+{
+  "globs": ["**/*.md"],
+  "config": {
+      "ul-indent": { "indent": 4 },
+      "ul-style": { "style": "dash" },
+      "emphasis-style": { "style": "asterisk" },
+      "no-duplicate-heading": { "siblings_only": true },
+      "no-inline-html": {
+          "allowed_elements": ["br", "details", "iframe", "summary"]
+      },
+      "no-trailing-spaces": { "br_spaces": 0 },
+      "line-length": false,
+      "no-bare-urls": false,
+      "no-emphasis-as-heading": false,
+      "link-fragments": false,
+      "no-duplicate-docusaurus-ids": true
+  },
+  "customRules": ["./markdownlint-custom/rule-no-duplicate-docusaurus-ids.js"],
+  "ignores": ["node_modules", "i18n"]
+}

docs/general/ad-filtering/create-own-filters.md

@@ -65,7 +65,7 @@ By default, such rules do not work for document requests. This means that the `|
 
 - `https://example.org/banner/img`
 
-### Basic rule modifiers {#basic-rule-modifiers}
+### Basic rule modifiers {#basic-rule-modifiers-examples}
 
 Filtering rules support numerous modifiers that allow you to fine-tune the rule behavior. Here is an example of a rule with some simple modifiers.
 
@@ -236,7 +236,7 @@ Safari Converter supports a substantial subset of [basic rules](#basic-rules) an
 - `$replace`
 - `$urltransform`
 
-#### Cosmetic rules
+#### Cosmetic rules {#cosmetic-rules-safari-limitations}
 
 Safari Converter supports most of the [cosmetic rules](#cosmetic-rules) although only element hiding rules with basic CSS selectors are supported natively via Safari Content Blocking, everything else needs to be interpreted by an additional extension.
 
@@ -261,7 +261,7 @@ For scriptlet rules, it is **very important** that they are run as early as poss
 
 :::
 
-#### HTML filtering rules
+#### HTML filtering rules {#html-filtering-rules-safari}
 
 [HTML filtering rules](#html-filtering-rules) are **not supported** and will not be supported in the future. Unfortunately, Safari does not provide necessary technical capabilities to implement them.
 

markdownlint-custom/rule-no-duplicate-docusaurus-ids.js

@@ -0,0 +1,54 @@
+const { createSlugger, parseMarkdownHeadingId } = require('@docusaurus/utils');
+
+/**
+ * Custom rule for markdownlint to prevent duplicate heading IDs as generated by Docusaurus.
+ *
+ * @type {import("markdownlint").Rule}
+ */
+module.exports = {
+    names: ['no-duplicate-docusaurus-ids'],
+    description: 'Prevent duplicate heading IDs as generated by Docusaurus',
+    tags: ['headings', 'anchors', 'docusaurus'],
+    parser: 'micromark',
+    function(params, onError) {
+        const { tokens } = params.parsers.micromark;
+        const slugger = createSlugger();
+        const slugMap = new Map();
+
+        for (const token of tokens) {
+            if (token.type !== 'atxHeading' && token.type !== 'setextHeading') {
+                continue;
+            }
+
+            const textNode = token.children.find(
+                (child) => child.type === 'atxHeadingText' || child.type === 'setextHeadingText',
+            );
+
+            if (!textNode) {
+                continue;
+            }
+
+            const { text, id } = parseMarkdownHeadingId(textNode.text);
+            // If ID provided (e.g. `# title {#id}`), use it, otherwise generate slug from text
+            const slug = id || slugger.slug(text);
+
+            if (!slugMap.has(slug)) {
+                slugMap.set(slug, []);
+            }
+
+            slugMap.get(slug).push({ lineNumber: token.startLine, text: textNode.text });
+        }
+
+        for (const [slug, entries] of slugMap.entries()) {
+            if (entries.length > 1) {
+                for (const { lineNumber, text } of entries) {
+                    onError({
+                        lineNumber,
+                        detail: `Duplicate heading ID: "${slug}", causing conflict in ToC`,
+                        context: text,
+                    });
+                }
+            }
+        }
+    },
+};

package.json

@@ -12,7 +12,7 @@
     "serve": "docusaurus serve",
     "write-translations": "docusaurus write-translations",
     "write-heading-ids": "docusaurus write-heading-ids",
-    "lint:md": "markdownlint .",
+    "lint:md": "markdownlint-cli2",
     "crowdin": "crowdin",
     "crowdin:sync": "docusaurus write-translations && crowdin upload && crowdin download --export-only-approved"
   },
@@ -45,7 +45,8 @@
     ]
   },
   "devDependencies": {
-    "markdownlint": "^0.29.0",
-    "markdownlint-cli": "^0.35.0"
+    "@docusaurus/utils": "^2.2.0",
+    "markdownlint": "^0.37.4",
+    "markdownlint-cli2": "^0.17.2"
   }
 }