fix(metadata): use short deprecation anchors

.changeset/short-deprecation-links.md

@@ -0,0 +1,5 @@
+---
+'@node-core/doc-kit': patch
+---
+
+Use short `DEP` codes for deprecation heading anchors.

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

@@ -29,7 +29,9 @@ const buildHeading = ({ data, children, depth }, index, parent, legacySlug) => {
     // to be converted into Rehype nodes
     ...children,
     // Legacy anchor alias to preserve old external links
-    createElement('span', createElement(`a#${legacySlug}`)),
+    ...(legacySlug === data.slug
+      ? []
+      : [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(

src/generators/metadata/constants.mjs

@@ -12,6 +12,9 @@ export const DOC_API_SLUGS_REPLACEMENTS = [
   { from: /^(?!-)(?!-+$).*?(--+)/g, to: '-' }, // Replace multiple hyphens
 ];
 
+// Matches Node.js deprecation headings such as "DEP0001: Description".
+export const DEPRECATION_HEADING_REGEX = /^(DEP\d+):/;
+
 // These are regular expressions used to determine if a given Markdown heading
 // is a specific type of API Doc entry (e.g., Event, Class, Method, etc)
 // and to extract the inner content of said Heading to be used as the API doc entry name

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

@@ -69,6 +69,38 @@ describe('parseApiDoc', () => {
     });
   });
 
+  describe('deprecation headings', () => {
+    it('uses the DEP code as the slug on the deprecations page', () => {
+      const tree = u('root', [
+        h('DEP0001: http.OutgoingMessage.prototype.flush'),
+      ]);
+      const [entry] = parseApiDoc({ path: '/deprecations', tree }, typeMap);
+
+      assert.strictEqual(entry.heading.data.slug, 'DEP0001');
+    });
+
+    it('deduplicates repeated DEP code slugs', () => {
+      const tree = u('root', [
+        h('DEP0001: first deprecated API'),
+        h('DEP0001: second deprecated API'),
+      ]);
+      const entries = parseApiDoc({ path: '/deprecations', tree }, typeMap);
+
+      assert.strictEqual(entries[0].heading.data.slug, 'DEP0001');
+      assert.strictEqual(entries[1].heading.data.slug, 'DEP0001-1');
+    });
+
+    it('uses normal slugs for DEP headings outside the deprecations page', () => {
+      const tree = u('root', [h('DEP0190: some section heading')]);
+      const [entry] = parseApiDoc({ path, tree }, typeMap);
+
+      assert.strictEqual(
+        entry.heading.data.slug,
+        'dep0190-some-section-heading'
+      );
+    });
+  });
+
   describe('YAML metadata', () => {
     it('extracts added_in', () => {
       const tree = u('root', [h('fs'), yaml('added: v0.1.0')]);

src/generators/metadata/utils/parse.mjs

@@ -21,7 +21,10 @@ import {
 import { UNIST } from '../../../utils/queries/index.mjs';
 import { getRemark as remark } from '../../../utils/remark.mjs';
 import { relative } from '../../../utils/url.mjs';
-import { IGNORE_STABILITY_STEMS } from '../constants.mjs';
+import {
+  DEPRECATION_HEADING_REGEX,
+  IGNORE_STABILITY_STEMS,
+} from '../constants.mjs';
 import { resolveTypeAnnotations } from './resolveTypes.mjs';
 
 /**
@@ -44,6 +47,20 @@ export const parseApiDoc = ({ path, tree, mdx = false }, typeMap) => {
   // Slug the API (We use a non-class slugger, since we are fairly certain that `path` is unique)
   const api = slug(path.slice(1).replace(sep, '-'));
 
+  /**
+   * Creates a stable slug for a heading in the current API document.
+   * @param {string} text Heading text to slug.
+   * @returns {string} The generated heading slug.
+   */
+  const getHeadingSlug = text => {
+    const deprecationHeading =
+      api === 'deprecations' && DEPRECATION_HEADING_REGEX.exec(text);
+
+    return deprecationHeading
+      ? nodeSlugger.slug(deprecationHeading[1]).toUpperCase()
+      : nodeSlugger.slug(text);
+  };
+
   // Get all Markdown Footnote definitions from the tree
   const markdownDefinitions = selectAll('definition', tree);
 
@@ -96,7 +113,7 @@ export const parseApiDoc = ({ path, tree, mdx = false }, typeMap) => {
     });
 
     // Generate slug and update heading data
-    metadata.heading.data.slug = nodeSlugger.slug(metadata.heading.data.text);
+    metadata.heading.data.slug = getHeadingSlug(metadata.heading.data.text);
 
     // Find the next heading to determine section boundaries
     const nextHeadingNode =