diff --git a/src/generators/metadata/constants.mjs b/src/generators/metadata/constants.mjs
index 614b30ef..f913c5b0 100644
--- a/src/generators/metadata/constants.mjs
+++ b/src/generators/metadata/constants.mjs
@@ -6,7 +6,8 @@ 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
+  { from: /(?<=[^_])_+/g, to: '-' }, // Replace internal/trailing underscores with a hyphen
   { from: /^-+(?!-*$)/g, to: '' }, // Remove any leading hyphens
   { from: /(?<!^-*)-+$/g, to: '' }, // Remove any trailing hyphens
   { from: /^(?!-+$).*?(--+)/g, to: '-' }, // Replace multiple hyphens
diff --git a/src/generators/metadata/utils/__tests__/slugger.test.mjs b/src/generators/metadata/utils/__tests__/slugger.test.mjs
index 40bedf3a..fe15d68c 100644
--- a/src/generators/metadata/utils/__tests__/slugger.test.mjs
+++ b/src/generators/metadata/utils/__tests__/slugger.test.mjs
@@ -25,7 +25,7 @@ describe('slug', () => {
   });
 
   describe('special character to hyphen replacement', () => {
-    it('replaces underscores with hyphens', () => {
+    it('replaces underscores with hyphens (except leading)', () => {
       assert.strictEqual(slug('foo_bar', identity), 'foo-bar');
     });
 
@@ -46,6 +46,16 @@ 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');
+    });
+  });
+
   describe('leading hyphen removal', () => {
     it('removes a single leading hyphen', () => {
       assert.strictEqual(slug('-foo', identity), 'foo');
@@ -85,13 +95,21 @@ describe('slug', () => {
       assert.strictEqual(slug('Hello World'), 'hello-world');
     });
 
-    it('converts underscored names to hyphenated slugs', () => {
+    it('converts internal underscored names to hyphenated slugs', () => {
       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 (preserves leading underscores)', () => {
+      assert.strictEqual(slug('__dirname'), '__dirname');
+    });
+
+    it('generates correct slug for __filename (preserves leading underscores)', () => {
+      assert.strictEqual(slug('__filename'), '__filename');
+    });
   });
 });