@@ -13,12 +13,31 @@ import fs from 'fs';
 import GithubSlugger from 'github-slugger';
 import { HEADING_ID } from '../../plugins/remark-heading-id.mjs';
 
+// Emphasis, per CommonMark: `*` opens and closes anywhere, including inside a
+// word, while `_` does not do so intraword. Keeping that distinction is what
+// lets an identifier heading (`flexible_http_request`,
+// `canister_inspect_message`) keep the underscores the site slugs it with,
+// while *emphasis* is still stripped. One rule over both delimiters read
+// `_http_` as emphasis and dropped it.
+const STAR_EMPHASIS = /\*{1,3}([^*]+)\*{1,3}/g;
+const UNDERSCORE_EMPHASIS = /(^|[^\w])_{1,3}([^_]+)_{1,3}(?=[^\w]|$)/g;
+
 function renderedText(heading) {
-  return heading
-    .replace(/`([^`]*)`/g, '$1')
-    .replace(/\[([^\]]*)\]\([^)]*\)/g, '$1')
-    .replace(/[*_]{1,3}([^*_]+)[*_]{1,3}/g, '$1')
-    .replace(/<[^>]+>/g, '')
+  // A link's text can hold a code span, so links are unwrapped first, over the
+  // whole heading.
+  const linked = heading.replace(/\[([^\]]*)\]\([^)]*\)/g, '$1');
+  // Inline code is literal, so no other rule may reach inside it.
+  return linked
+    .split(/(`[^`]*`)/g)
+    .map((part, i) =>
+      i % 2 === 1
+        ? part.slice(1, -1)
+        : part
+            .replace(STAR_EMPHASIS, '$1')
+            .replace(UNDERSCORE_EMPHASIS, '$1$2')
+            .replace(/<[^>]+>/g, '')
+    )
+    .join('')
     .trim();
 }