feat: restore legacy anchor alias to preserve old links

Fixes: #697

Author: shivxmsharma

src/generators/legacy-html/utils/__tests__/slugger.test.mjs

@@ -0,0 +1,49 @@
+'use strict';
+
+import assert from 'node:assert/strict';
+import { describe, it } from 'node:test';
+
+import { getLegacySlug } from '../slugger.mjs';
+
+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');
+  });
+
+  it('deduplicates with a counter when deduplicateFn is provided', () => {
+    const legacyIdCounters = { __proto__: null };
+    const deduplicateFn = id => {
+      if (legacyIdCounters[id] !== undefined) {
+        return `${id}_${++legacyIdCounters[id]}`;
+      }
+      legacyIdCounters[id] = 0;
+      return id;
+    };
+
+    assert.strictEqual(getLegacySlug('Hello', 'fs', deduplicateFn), 'fs_hello');
+    assert.strictEqual(
+      getLegacySlug('Hello', 'fs', deduplicateFn),
+      'fs_hello_1'
+    );
+    assert.strictEqual(
+      getLegacySlug('Hello', 'fs', deduplicateFn),
+      'fs_hello_2'
+    );
+    assert.strictEqual(getLegacySlug('World', 'fs', deduplicateFn), 'fs_world');
+  });
+});

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

@@ -5,6 +5,7 @@ import { u as createTree } from 'unist-builder';
 import { SKIP, visit } from 'unist-util-visit';
 
 import buildExtraContent from './buildExtraContent.mjs';
+import { getLegacySlug } from './slugger.mjs';
 import getConfig from '../../../utils/configuration/index.mjs';
 import {
   GITHUB_BLOB_URL,
@@ -20,12 +21,21 @@ import { QUERIES, UNIST } from '../../../utils/queries/index.mjs';
  * @param {import('unist').Parent} parent The parent node of the current node
  * @returns {import('hast').Element} The HTML AST tree of the heading content
  */
-const buildHeading = ({ data, children, depth }, index, parent) => {
+const buildHeading = (
+  { data, children, depth },
+  index,
+  parent,
+  apiStem,
+  deduplicateFn
+) => {
+  const legacySlug = getLegacySlug(data.text, apiStem, deduplicateFn);
   // Creates the heading element with the heading text and the link to the heading
   const headingElement = createElement(`h${depth + 1}`, [
     // 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#${legacySlug}`)),
     // Creates the element that references the link to the heading
     // (The `#` anchor on the right of each Heading section)
     createElement(
@@ -220,6 +230,16 @@ const buildMetadataElement = (node, remark) => {
  * @param {import('unified').Processor} remark The Remark instance to be used to process
  */
 export default (headNodes, metadataEntries, remark) => {
+  // Legacy slug counter tracking for 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;
+  };
   // Creates the root node for the content
   const parsedNodes = createTree(
     'root',
@@ -229,7 +249,9 @@ export default (headNodes, metadataEntries, remark) => {
       const content = structuredClone(entry.content);
 
       // Parses the Heading nodes into Heading elements
-      visit(content, UNIST.isHeading, buildHeading);
+      visit(content, UNIST.isHeading, (node, index, parent) =>
+        buildHeading(node, index, parent, entry.api, legacyDeduplicateFn)
+      );
 
       // Parses the Blockquotes into Stability elements
       // This is treated differently as we want to preserve the position of a Stability Index

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

@@ -0,0 +1,23 @@
+'use strict';
+
+const notAlphaNumerics = /[^a-z0-9]+/g;
+const edgeUnderscores = /^_+|_+$/g;
+const notAlphaStart = /^[^a-z]/;
+
+/**
+ * Generates a legacy-style slug to preserve old anchor links.
+ *
+ * @param {string} text The heading text
+ * @param {string} apiStem 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 = (text, apiStem, deduplicateFn) => {
+  let id = `${apiStem}_${text}`
+    .toLowerCase()
+    .replace(notAlphaNumerics, '_')
+    .replace(edgeUnderscores, '')
+    .replace(notAlphaStart, '_$&');
+
+  return deduplicateFn ? deduplicateFn(id) : id;
+};