feat: restore legacy anchor alias to preserve old links

Fixes: #697

Author: shivxmsharma

src/generators/jsx-ast/utils/buildContent.mjs

@@ -128,12 +128,14 @@ export const extractHeadingContent = content => {
  * @param {import('unist').Node|null} changeElement - The change history element, if available
  */
 export const createHeadingElement = (content, changeElement) => {
-  const { type, slug } = content.data;
+  const { type, slug, legacySlug } = content.data;
 
   let headingContent = extractHeadingContent(content);
 
   // Build heading with anchor link
   const headingWrapper = createElement('div', [
+    // Legacy anchor alias to preserve old external links
+    createElement('a', { id: legacySlug }),
     createElement(
       `h${content.depth}`,
       { id: slug },

src/generators/legacy-html/utils/buildContent.mjs

@@ -26,6 +26,8 @@ const buildHeading = ({ data, children, depth }, index, parent) => {
     // The inner Heading markdown content is still using Remark nodes, and they need
     // to be converted into Rehype nodes
     ...children,
+    // Legacy anchor alias to preserve old external links
+    createElement('span', createElement(`a#${data.legacySlug}`)),
     // Creates the element that references the link to the heading
     // (The `#` anchor on the right of each Heading section)
     createElement(

src/generators/metadata/types.d.ts

@@ -100,6 +100,8 @@ export interface HeadingData extends Data {
   name: string;
   /** URL-safe slug derived from heading text */
   slug: string;
+  /** Legacy slug for backward-compatible anchor links */
+  legacySlug: string;
   /** Optional type classification */
   type?: HeadingType;
 }

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

@@ -3,7 +3,7 @@
 import assert from 'node:assert/strict';
 import { describe, it } from 'node:test';
 
-import createNodeSlugger, { slug } from '../slugger.mjs';
+import createNodeSlugger, { slug, getLegacySlug } from '../slugger.mjs';
 
 const identity = str => str;
 
@@ -116,3 +116,39 @@ describe('createNodeSlugger', () => {
     assert.strictEqual(slugger2.slug('Hello'), 'hello');
   });
 });
+
+describe('getLegacySlug', () => {
+  it('prefixes with api stem and uses underscores', () => {
+    assert.strictEqual(getLegacySlug('File System', 'fs'), 'fs_file_system');
+  });
+
+  it('replaces special characters with underscores', () => {
+    assert.strictEqual(
+      getLegacySlug('fs.readFile(path)', 'fs'),
+      'fs_fs_readfile_path'
+    );
+  });
+
+  it('strips leading and trailing underscores', () => {
+    assert.strictEqual(getLegacySlug('Hello', 'fs'), 'fs_hello');
+  });
+
+  it('prefixes with underscore when result starts with non-alpha', () => {
+    assert.strictEqual(getLegacySlug('123 test', '0num'), '_0num_123_test');
+  });
+});
+
+describe('createNodeSlugger legacySlug', () => {
+  it('deduplicates repeated legacy slugs with a counter', () => {
+    const slugger = createNodeSlugger();
+    assert.strictEqual(slugger.legacySlug('Hello', 'fs'), 'fs_hello');
+    assert.strictEqual(slugger.legacySlug('Hello', 'fs'), 'fs_hello_1');
+    assert.strictEqual(slugger.legacySlug('Hello', 'fs'), 'fs_hello_2');
+  });
+
+  it('does not deduplicate different titles', () => {
+    const slugger = createNodeSlugger();
+    assert.strictEqual(slugger.legacySlug('First', 'fs'), 'fs_first');
+    assert.strictEqual(slugger.legacySlug('Second', 'fs'), 'fs_second');
+  });
+});

src/generators/metadata/utils/parse.mjs

@@ -92,6 +92,10 @@ export const parseApiDoc = ({ path, tree }, typeMap) => {
 
     // Generate slug and update heading data
     metadata.heading.data.slug = nodeSlugger.slug(metadata.heading.data.text);
+    metadata.heading.data.legacySlug = nodeSlugger.legacySlug(
+      metadata.heading.data.text,
+      api
+    );
 
     // Find the next heading to determine section boundaries
     const nextHeadingNode =

src/generators/metadata/utils/slugger.mjs

@@ -13,16 +13,24 @@ const createNodeSlugger = () => {
   const slugger = new GitHubSlugger();
   const slugFn = slugger.slug.bind(slugger);
 
+  // Legacy slug counter tracking (mirrors old Node.js deduplication)
+  const legacyIdCounters = { __proto__: null };
+
+  /** Deduplicates legacy slugs by appending an incremented counter */
+  const legacyDeduplicateFn = id => {
+    if (legacyIdCounters[id] !== undefined) {
+      return `${id}_${++legacyIdCounters[id]}`;
+    }
+    legacyIdCounters[id] = 0;
+    return id;
+  };
+
   return {
     ...slugger,
-    /**
-     * Creates a new slug based on the provided string
-     *
-     * @param {string} title The title to be parsed into a slug
-     */
-    // Applies certain string replacements that are specific
-    // to the way how Node.js generates slugs/anchor IDs
+    /** Creates a new slug with Node.js-specific replacements applied */
     slug: title => slug(title, slugFn),
+    /** Creates a legacy-style slug to preserve old anchor links */
+    legacySlug: (title, api) => getLegacySlug(title, api, legacyDeduplicateFn),
   };
 };
 
@@ -36,4 +44,29 @@ export const slug = (title, slugFn = defaultSlugFn) =>
     slugFn(title)
   );
 
+// Legacy slug algorithm regex patterns (from old Node.js doc generator)
+const notAlphaNumerics = /[^a-z0-9]+/g;
+const edgeUnderscores = /^_+|_+$/g;
+const notAlphaStart = /^[^a-z]/;
+
+/**
+ * Generates a legacy-style slug to preserve old anchor links.
+ * The old Node.js doc generator used this format: filename_headingtext
+ * with non-alphanumerics replaced by underscores.
+ *
+ * @param {string} title The heading text
+ * @param {string} api The API file identifier (e.g. 'fs', 'http')
+ * @param {(id: string) => string} [deduplicateFn] Optional function for counter-based deduplication
+ * @returns {string} The legacy slug
+ */
+export const getLegacySlug = (title, api, deduplicateFn) => {
+  let id = `${api}_${title}`
+    .toLowerCase()
+    .replace(notAlphaNumerics, '_')
+    .replace(edgeUnderscores, '')
+    .replace(notAlphaStart, '_$&');
+
+  return deduplicateFn ? deduplicateFn(id) : id;
+};
+
 export default createNodeSlugger;