From 079de38a668b5b7c20087815a3bfbf526e63cb6a Mon Sep 17 00:00:00 2001
From: Sujal Goel <goelsujal9@gmail.com>
Date: Thu, 9 Apr 2026 11:23:31 +0530
Subject: [PATCH 1/2] fix(metadata): preserve -- prefix in anchor IDs for CLI
 flags

Two regexes in DOC_API_SLUGS_REPLACEMENTS were stripping -- from the
start of slugs, turning --permission into permission and breaking
existing links.

Fixes #757
---
 src/generators/metadata/constants.mjs              |  4 ++--
 .../metadata/utils/__tests__/slugger.test.mjs      | 14 ++++++++++++--
 2 files changed, 14 insertions(+), 4 deletions(-)

diff --git a/src/generators/metadata/constants.mjs b/src/generators/metadata/constants.mjs
index e8ac140b..d9cbd2d8 100644
--- a/src/generators/metadata/constants.mjs
+++ b/src/generators/metadata/constants.mjs
@@ -7,9 +7,9 @@ export const DOC_API_SLUGS_REPLACEMENTS = [
   { from: /node.js/i, to: 'nodejs' }, // Replace Node.js
   { from: /&/, to: '-and-' }, // Replace &
   { from: /[/,:;\\ ]/g, to: '-' }, // Replace /,:;\. and whitespace
-  { from: /^-+(?!-*$)/g, to: '' }, // Remove any leading hyphens
+  { from: /^-(?=[^-])/g, to: '' }, // Remove a single leading hyphen (preserves -- prefix for CLI flags)
   { from: /(?<!^-*)-+$/g, to: '' }, // Remove any trailing hyphens
-  { from: /^(?!-+$).*?(--+)/g, to: '-' }, // Replace multiple hyphens
+  { from: /^(?!-+$)[^-].*?(--+)/g, to: '-' }, // Replace multiple consecutive hyphens (not at start)
 ];
 
 // These are regular expressions used to determine if a given Markdown heading
diff --git a/src/generators/metadata/utils/__tests__/slugger.test.mjs b/src/generators/metadata/utils/__tests__/slugger.test.mjs
index 1a123afa..a25a37cd 100644
--- a/src/generators/metadata/utils/__tests__/slugger.test.mjs
+++ b/src/generators/metadata/utils/__tests__/slugger.test.mjs
@@ -51,8 +51,8 @@ describe('slug', () => {
       assert.strictEqual(slug('-foo', identity), 'foo');
     });
 
-    it('removes multiple leading hyphens', () => {
-      assert.strictEqual(slug('--foo', identity), 'foo');
+    it('preserves double leading hyphens (CLI flag prefix)', () => {
+      assert.strictEqual(slug('--foo', identity), '--foo');
     });
 
     it('preserves an all-hyphen string', () => {
@@ -80,6 +80,16 @@ describe('slug', () => {
     });
   });
 
+  describe('cli flag anchor preservation', () => {
+    it('preserves -- prefix for CLI flags', () => {
+      assert.strictEqual(slug('--permission', identity), '--permission');
+    });
+
+    it('preserves -- prefix for multi-word CLI flags', () => {
+      assert.strictEqual(slug('--allow-fs-read', identity), '--allow-fs-read');
+    });
+  });
+
   describe('integration with github-slugger', () => {
     it('lowercases and hyphenates a plain title', () => {
       assert.strictEqual(slug('Hello World'), 'hello-world');

From a15edcab0bb2590590288bf412500abac99e562f Mon Sep 17 00:00:00 2001
From: Sujal Goel <goelsujal9@gmail.com>
Date: Fri, 10 Apr 2026 19:57:58 +0530
Subject: [PATCH 2/2] test(metadata): remove redundant CLI flag slug tests

---
 .../metadata/utils/__tests__/slugger.test.mjs          | 10 ----------
 1 file changed, 10 deletions(-)

diff --git a/src/generators/metadata/utils/__tests__/slugger.test.mjs b/src/generators/metadata/utils/__tests__/slugger.test.mjs
index a25a37cd..587632a4 100644
--- a/src/generators/metadata/utils/__tests__/slugger.test.mjs
+++ b/src/generators/metadata/utils/__tests__/slugger.test.mjs
@@ -80,16 +80,6 @@ describe('slug', () => {
     });
   });
 
-  describe('cli flag anchor preservation', () => {
-    it('preserves -- prefix for CLI flags', () => {
-      assert.strictEqual(slug('--permission', identity), '--permission');
-    });
-
-    it('preserves -- prefix for multi-word CLI flags', () => {
-      assert.strictEqual(slug('--allow-fs-read', identity), '--allow-fs-read');
-    });
-  });
-
   describe('integration with github-slugger', () => {
     it('lowercases and hyphenates a plain title', () => {
       assert.strictEqual(slug('Hello World'), 'hello-world');