Improve slugger for headers containing HTML

Resolves #3023

Author: Gerrit0

.gitignore

@@ -17,8 +17,8 @@ yarn-error.log
 /coverage/
 /dist/
 /docs
-/docs-site
 /docs2
+/docs-*
 /td*.json
 
 typedoc*.tgz

CHANGELOG.md

@@ -13,6 +13,7 @@ title: Changelog
 ## Bug Fixes
 
 - Fixed conversion of auto-accessor types on properties with the `accessor` keyword, #3019.
+- Improved handling of HTML tags within headers for anchor generation, #3023.
 
 ## v0.28.13 (2025-09-14)
 

scripts/rebuild_specs.js

@@ -81,7 +81,7 @@ const conversions = [
  */
 function rebuildConverterTests(dirs) {
     const program = ts.createProgram(app.options.getFileNames(), {
-        ...app.options.getCompilerOptions(),
+        ...app.options.getCompilerOptions(app.logger),
         noEmit: true,
     });
 

src/lib/output/themes/MarkedPlugin.tsx

@@ -409,10 +409,19 @@ export class MarkedPlugin extends ContextAwareRendererComponent {
 }
 
 function getTokenTextContent(token: md.Token): string {
+    // If there are children, we want their text content, not the full text content
     if (token.children) {
         return token.children.map(getTokenTextContent).join("");
     }
-    return token.content;
+
+    // If this is a simple text fragment, use its content
+    if (token.type === "text") {
+        return token.content;
+    }
+
+    // Otherwise this is some type of metadata token (e.g. header_open)
+    // or a HTML tag token. Don't include it in the text content.
+    return "";
 }
 
 const kindNames = ["note", "tip", "important", "warning", "caution"];

src/lib/output/themes/default/Slugger.ts

@@ -1,5 +1,5 @@
 import { getSimilarValues } from "#utils";
-import type { TypeDocOptionMap } from "../../../utils/index.js";
+import type { TypeDocOptionMap } from "#node-utils";
 
 /**
  * Responsible for getting a unique anchor for elements within a page.
@@ -8,20 +8,28 @@ export class Slugger {
     private seen = new Map<string, number>();
 
     private serialize(value: string) {
-        // Notes:
-        // There are quite a few trade-offs here.
+        // There are quite a few trade-offs here. We used to remove HTML tags here,
+        // but TypeDoc now removes the HTML tags before passing text into the slug
+        // method, which allows us to skip doing that here. This improves the slugger
+        // generation for headers which look like the following:
+        // (html allowed in markdown)
+        // # test &lt;t&gt;
+        // (html disallowed in markdown)
+        // # test <t>
+        // both of the above should slug to test-t
 
         return (
             value
                 .trim()
-                // remove html tags
-                .replace(/<[!/a-z].*?>/gi, "")
                 // remove unwanted chars
                 .replace(
                     /[\u2000-\u206F\u2E00-\u2E7F\\'!"#$%&()*+,./:;<=>?@[\]^`{|}~]/g,
                     "",
                 )
+                // change whitespace to dash
                 .replace(/\s/g, "-")
+                // combine adjacent dashes
+                .replace(/--+/, "-")
         );
     }
 

src/lib/utils-common/general.ts

@@ -45,6 +45,7 @@ export function assertNever(x: never): never {
 
 export function assert(x: unknown, message = "Assertion failed"): asserts x {
     if (!x) {
+        debugger;
         throw new Error(message);
     }
 }

src/test/converter2/renderer/renderer-readme.md

@@ -0,0 +1,3 @@
+# gh3023 <test>
+
+Anchor for above heading should be `gh3023-test`

src/test/output/Slugger.test.ts

@@ -13,4 +13,15 @@ describe("Slugger", () => {
         equal(slugger.slug("model"), "model");
         equal(slugger.slug("Model"), "Model-1");
     });
+
+    it("Handles embedded html characters", () => {
+        const slugger = new Slugger({ lowercase: true });
+        equal(slugger.slug("test <T>"), "test-t");
+        equal(slugger.slug("test <T>"), "test-t-1");
+    });
+
+    it("Handles adjacent whitespace", () => {
+        const slugger = new Slugger({ lowercase: true });
+        equal(slugger.slug("test    test2"), "test-test2");
+    });
 });

src/test/renderer/specs/classes/BaseClass.json

@@ -401,7 +401,9 @@
                                                     {
                                                         "div.tsd-description": [
                                                             {
-                                                                "div.tsd-comment.tsd-typography": "<p>Base class method</p>\n"
+                                                                "div.tsd-comment.tsd-typography": {
+                                                                    "p": "Base class method"
+                                                                }
                                                             },
                                                             {
                                                                 "div.tsd-parameters": [

src/test/renderer/specs/classes/GenericClass.json

@@ -27,7 +27,9 @@
                 },
                 {
                     "section.tsd-panel.tsd-comment": {
-                        "div.tsd-comment.tsd-typography": "<p>Generic class</p>\n"
+                        "div.tsd-comment.tsd-typography": {
+                            "p": "Generic class"
+                        }
                     }
                 },
                 {