fix(api-markdown-documenter): Escape child content of HTML headings (#25494)

Fixed an issue where HTML headings were being generated with unescaped
child content. This caused headings for signatures with generic type
parameters to be interpreted like HTML rather than as plain text.

See updated test collateral of example issues.

Author: Josmithr

tools/api-markdown-documenter/CHANGELOG.md

@@ -7,6 +7,8 @@ This aligns the behavior of this function with other section creation helpers.
 
 ### 🐞 Bug Fixes
 
+- Fixed an issue where HTML headings were being generated with unescaped child content.
+  This caused headings for signatures with generic type parameters to be interpreted like HTML rather than as plain text.
 - Fixed an issue where HTML table cell content was generated with line breaks for formatting.
   This would break Markdown table syntax.
   Line breaks are now omitted in this context.

tools/api-markdown-documenter/src/mdast/Normalize.ts

@@ -3,6 +3,8 @@
  * Licensed under the MIT License.
  */
 
+import type { Element } from "hast";
+import { toHtml } from "hast-util-to-html";
 import type { BlockContent, Break, Html, Nodes, Root, RootContent, Strong } from "mdast";
 
 import type { Section } from "./Section.js";
@@ -130,25 +132,44 @@ function transformAsHeading(
 	// Markdown headings don't natively support anchor IDs.
 	// If the heading has an ID set, we will render it as an HTML element.
 	// While there are extended syntax options for Markdown that do support IDs, none of them are widely supported.
-	return headingNode.id === undefined
-		? [
+	if (headingNode.id !== undefined) {
+		// Create hast representation of HTML heading, then convert to string representation.
+		// This ensures that contents are escaped properly.
+		const htmlHeadingNode: Element = {
+			type: "element",
+			tagName: `h${headingLevel}`,
+			properties: {
+				id: headingNode.id,
+			},
+			children: [
 				{
-					type: "heading",
-					depth: headingLevel,
-					children: [
-						{
-							type: "text",
-							value: headingNode.title,
-						},
-					],
+					type: "text",
+					value: headingNode.title,
 				},
-			]
-		: [
+			],
+		};
+		const htmlHeadingString = toHtml(htmlHeadingNode, {});
+
+		return [
+			{
+				type: "html",
+				value: htmlHeadingString,
+			},
+		];
+	}
+
+	return [
+		{
+			type: "heading",
+			depth: headingLevel,
+			children: [
 				{
-					type: "html",
-					value: `<h${headingLevel} id="${headingNode.id}">${headingNode.title}</h${headingLevel}>`,
+					type: "text",
+					value: headingNode.title,
 				},
-			];
+			],
+		},
+	];
 }
 
 function transformAsBoldText(headingNode: SectionHeading): BlockContent[] {

tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/default-config/test-suite-a/testinterfacewithcallsignature-interface.md

@@ -18,7 +18,7 @@ export interface TestInterfaceWithCallSignature
 
 ## Call Signature Details
 
-<h3 id="_call_-callsignature"><T extends string>(foo: T): number & T</h3>
+<h3 id="_call_-callsignature">&#x3C;T extends string>(foo: T): number &#x26; T</h3>
 
 Test call signature.
 

tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/flat-config/test-suite-a.md

@@ -382,7 +382,7 @@ export interface TestInterfaceWithCallSignature
 
 ### Call Signature Details
 
-<h4 id="testinterfacewithcallsignature-_call_-callsignature"><T extends string>(foo: T): number & T</h4>
+<h4 id="testinterfacewithcallsignature-_call_-callsignature">&#x3C;T extends string>(foo: T): number &#x26; T</h4>
 
 Test call signature.