fix: keep underscores in identifier heading anchors

package.json

@@ -29,6 +29,8 @@
     "@resvg/resvg-js": "^2.6.2",
     "github-slugger": "^2.0.0",
     "glob": "^13.0.6",
-    "gray-matter": "^4.0.3"
+    "gray-matter": "^4.0.3",
+    "mdast-util-from-markdown": "^2.0.3",
+    "mdast-util-to-string": "^4.0.0"
   }
 }

scripts/lib/anchors.mjs

@@ -1,25 +1,39 @@
 // Heading ids as the site generates them.
 //
-// Starlight slugs the *rendered* heading text with github-slugger, so inline
-// markdown is stripped first and an explicit `{#id}` wins. Using the same
-// library rather than an approximation is deliberate: compared over the 2995
-// headings in docs/, a hand-rolled slug disagreed on 21 of them, all headings
-// containing an arrow, an ampersand, or `/*`.
+// Starlight slugs the *rendered* heading text with github-slugger, so the
+// heading is parsed to its text first and an explicit `{#id}` wins. Both steps
+// use the libraries the site itself uses rather than an approximation of them:
+// compared against the ids in a built site, every heading on all 200 pages
+// agrees, in both directions.
 //
 // Shared by scripts/validate.js (every page, every PR) and
 // scripts/sync-static-site.mjs (the synced tree, before it is written).
 
 import fs from 'fs';
 import GithubSlugger from 'github-slugger';
+import { fromMarkdown } from 'mdast-util-from-markdown';
+import { toString } from 'mdast-util-to-string';
 import { HEADING_ID } from '../../plugins/remark-heading-id.mjs';
 
-function renderedText(heading) {
-  return heading
-    .replace(/`([^`]*)`/g, '$1')
-    .replace(/\[([^\]]*)\]\([^)]*\)/g, '$1')
-    .replace(/[*_]{1,3}([^*_]+)[*_]{1,3}/g, '$1')
-    .replace(/<[^>]+>/g, '')
-    .trim();
+// The rendered text of a heading, which is what the site slugs: inline markdown
+// resolved away, so `code`, **strong**, [links](x) and raw HTML contribute their
+// text and nothing else. Parsed rather than pattern-matched, because inline
+// markdown does not reduce to a set of regexes. Two cases that defeated one:
+// `flexible_http_request` in a code span (an inner `_http_` read as emphasis,
+// so both underscores vanished), and `_foo_bar_`, where CommonMark pairs the
+// outer underscores and keeps the intraword one.
+//
+// Takes the whole line, `#` markers included. The text alone is not the same
+// document: "1. Create a canister" parses as an ordered list and renders as
+// "Create a canister", losing the number the site slugs into the id.
+//
+// One construct is out of reach: a footnote reference in a heading renders as
+// the note's *number*, which is assigned while the document is rendered, so no
+// parse of the heading alone can produce it. `## API[^note]` is `footnote-api1`
+// on the site. Neither CommonMark nor GFM parsing yields that, so a link to
+// such a heading would be reported as broken. No heading in docs/ does this.
+function renderedText(line) {
+  return toString(fromMarkdown(line), { includeHtml: false }).trim();
 }
 
 export function anchorsOfText(text) {
@@ -36,7 +50,7 @@ export function anchorsOfText(text) {
     if (!m) continue;
     // `{#id}` and `{$id}` both set an explicit id; the plugin accepts both.
     const explicit = HEADING_ID.exec(m[1]);
-    anchors.add(explicit ? explicit[1] : slugger.slug(renderedText(m[1])));
+    anchors.add(explicit ? explicit[1] : slugger.slug(renderedText(line)));
   }
   return anchors;
 }