fix(metadata): preserve -- prefix in anchor IDs for CLI flags

src/generators/metadata/constants.mjs

@@ -5,11 +5,10 @@ export const IGNORE_STABILITY_STEMS = ['documentation'];
 // These are string replacements specific to Node.js API docs for anchor IDs
 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: '-and-', pre: true }, // Replace & before slugging (slugger removes it without a separator)
+  { from: /=/g, to: '-', pre: true }, // Replace = before slugging (slugger removes it without a separator)
+  { from: /[/,:;\\ ]/g, to: '-' }, // Replace /,:;\ and whitespace
   { from: /(?<!^-*)-+$/g, to: '' }, // Remove any trailing hyphens
-  { from: /^(?!-+$).*?(--+)/g, to: '-' }, // Replace multiple hyphens
 ];
 
 // These are regular expressions used to determine if a given Markdown heading

src/generators/metadata/utils/__tests__/slugger.test.mjs

@@ -44,19 +44,9 @@ describe('slug', () => {
     it('replaces semicolons with hyphens', () => {
       assert.strictEqual(slug('foo;bar', identity), 'foo-bar');
     });
-  });
-
-  describe('leading hyphen removal', () => {
-    it('removes a single leading hyphen', () => {
-      assert.strictEqual(slug('-foo', identity), 'foo');
-    });
 
-    it('removes multiple leading hyphens', () => {
-      assert.strictEqual(slug('--foo', identity), 'foo');
-    });
-
-    it('preserves an all-hyphen string', () => {
-      assert.strictEqual(slug('---', identity), '---');
+    it('replaces equals signs with hyphens', () => {
+      assert.strictEqual(slug('foo=bar', identity), 'foo-bar');
     });
   });
 
@@ -70,13 +60,23 @@ describe('slug', () => {
     });
   });
 
-  describe('consecutive hyphen replacement', () => {
-    it('replaces from start of string up to and including double-hyphen with a single hyphen', () => {
-      assert.strictEqual(slug('foo--bar', identity), '-bar');
+  describe('cli flag anchors', () => {
+    it('preserves -- prefix for CLI flags', () => {
+      assert.strictEqual(slug('--permission', identity), '--permission');
+    });
+
+    it('preserves -x, --long-form mixed flag headings', () => {
+      assert.strictEqual(
+        slug('-p---print-script', identity),
+        '-p---print-script'
+      );
     });
 
-    it('does not fire on an all-hyphen string', () => {
-      assert.strictEqual(slug('---', identity), '---');
+    it('handles = in flag values', () => {
+      assert.strictEqual(
+        slug('-c-condition---conditions=condition', identity),
+        '-c-condition---conditions-condition'
+      );
     });
   });
 

src/generators/metadata/utils/slugger.mjs

@@ -30,10 +30,15 @@ const createNodeSlugger = () => {
  * @param {string} title
  * @param {typeof defaultSlugFn} slugFn
  */
-export const slug = (title, slugFn = defaultSlugFn) =>
-  DOC_API_SLUGS_REPLACEMENTS.reduce(
+export const slug = (title, slugFn = defaultSlugFn) => {
+  const preTitle = DOC_API_SLUGS_REPLACEMENTS.filter(r => r.pre).reduce(
+    (s, { from, to }) => s.replace(from, to),
+    title
+  );
+  return DOC_API_SLUGS_REPLACEMENTS.filter(r => !r.pre).reduce(
     (piece, { from, to }) => piece.replace(from, to),
-    slugFn(title)
+    slugFn(preTitle)
   );
+};
 
 export default createNodeSlugger;