fix: preserve underscores in slug generation for anchor link compatibility

src/generators/metadata/constants.mjs

@@ -6,7 +6,7 @@ export const IGNORE_STABILITY_STEMS = ['documentation'];
 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: '-' }, // Replace /,:;\ and whitespace (underscores are preserved)
   { from: /^-+(?!-*$)/g, to: '' }, // Remove any leading hyphens
   { from: /(?<!^-*)-+$/g, to: '' }, // Remove any trailing hyphens
   { from: /^(?!-+$).*?(--+)/g, to: '-' }, // Replace multiple hyphens

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

@@ -25,8 +25,8 @@ describe('slug', () => {
   });
 
   describe('special character to hyphen replacement', () => {
-    it('replaces underscores with hyphens', () => {
-      assert.strictEqual(slug('foo_bar', identity), 'foo-bar');
+    it('preserves underscores (does not replace with hyphens)', () => {
+      assert.strictEqual(slug('foo_bar', identity), 'foo_bar');
     });
 
     it('replaces forward slashes with hyphens', () => {
@@ -46,6 +46,24 @@ describe('slug', () => {
     });
   });
 
+  describe('underscore preservation (anchor link compatibility)', () => {
+    it('preserves leading underscores so __dirname slug matches #__dirname anchor', () => {
+      assert.strictEqual(slug('__dirname', identity), '__dirname');
+    });
+
+    it('preserves leading underscores so __filename slug matches #__filename anchor', () => {
+      assert.strictEqual(slug('__filename', identity), '__filename');
+    });
+
+    it('preserves underscores within names', () => {
+      assert.strictEqual(slug('child_process', identity), 'child_process');
+    });
+
+    it('preserves mixed underscores and other characters', () => {
+      assert.strictEqual(slug('foo_bar:baz', identity), 'foo_bar-baz');
+    });
+  });
+
   describe('leading hyphen removal', () => {
     it('removes a single leading hyphen', () => {
       assert.strictEqual(slug('-foo', identity), 'foo');
@@ -85,13 +103,21 @@ describe('slug', () => {
       assert.strictEqual(slug('Hello World'), 'hello-world');
     });
 
-    it('converts underscored names to hyphenated slugs', () => {
-      assert.strictEqual(slug('child_process'), 'child-process');
+    it('preserves underscores in names (no hyphenation)', () => {
+      assert.strictEqual(slug('child_process'), 'child_process');
     });
 
     it('handles titles with no special characters', () => {
       assert.strictEqual(slug('stability index'), 'stability-index');
     });
+
+    it('generates correct slug for __dirname', () => {
+      assert.strictEqual(slug('__dirname'), '__dirname');
+    });
+
+    it('generates correct slug for __filename', () => {
+      assert.strictEqual(slug('__filename'), '__filename');
+    });
   });
 });