fix: preserve inline heading content and stable slug ids

Author: RYGRIT

server/utils/readme.ts

@@ -219,6 +219,14 @@ function slugify(text: string): string {
     .replace(/^-|-$/g, '') // Trim leading/trailing hyphens
 }
 
+function getHeadingPlainText(text: string): string {
+  return decodeHtmlEntities(stripHtmlTags(text).trim())
+}
+
+function getHeadingSlugSource(text: string): string {
+  return stripHtmlTags(text).trim()
+}
+
 /**
  * Lazy ATX heading extension for marked: allows headings without a space after `#`.
  *
@@ -457,11 +465,17 @@ export async function renderReadmeHtml(
   let lastSemanticLevel = 2 // Start after h2 (the "Readme" section heading)
 
   // Shared heading processing for both markdown and HTML headings
-  function processHeading(depth: number, plainText: string, preservedAttrs = '') {
+  function processHeading(
+    depth: number,
+    displayHtml: string,
+    plainText: string,
+    slugSource: string,
+    preservedAttrs = '',
+  ) {
     const semanticLevel = calculateSemanticDepth(depth, lastSemanticLevel)
     lastSemanticLevel = semanticLevel
 
-    let slug = slugify(plainText)
+    let slug = slugify(slugSource)
     if (!slug) slug = 'heading'
 
     const count = usedSlugs.get(slug) ?? 0
@@ -473,13 +487,14 @@ export async function renderReadmeHtml(
       toc.push({ text: plainText, id, depth })
     }
 
-    return `<h${semanticLevel} id="${id}" data-level="${depth}"${preservedAttrs}><a href="#${id}">${plainText}</a></h${semanticLevel}>\n`
+    return `<h${semanticLevel} id="${id}" data-level="${depth}"${preservedAttrs}><a href="#${id}">${displayHtml}</a></h${semanticLevel}>\n`
   }
 
   renderer.heading = function ({ tokens, depth }: Tokens.Heading) {
-    const text = this.parser.parseInline(tokens)
-    const plainText = decodeHtmlEntities(stripHtmlTags(text).trim())
-    return processHeading(depth, plainText)
+    const displayHtml = this.parser.parseInline(tokens)
+    const plainText = getHeadingPlainText(displayHtml)
+    const slugSource = getHeadingSlugSource(displayHtml)
+    return processHeading(depth, displayHtml, plainText, slugSource)
   }
 
   // Intercept HTML headings so they get id, TOC entry, and correct semantic level.
@@ -489,10 +504,11 @@ export async function renderReadmeHtml(
   renderer.html = function ({ text }: Tokens.HTML) {
     let result = text.replace(htmlHeadingRe, (_, level, attrs = '', inner) => {
       const depth = parseInt(level)
-      const plainText = decodeHtmlEntities(stripHtmlTags(inner).trim())
+      const plainText = getHeadingPlainText(inner)
+      const slugSource = getHeadingSlugSource(inner)
       const align = /\balign=(["'])(.*?)\1/i.exec(attrs)?.[2]
       const preservedAttrs = align ? ` align="${align}"` : ''
-      return processHeading(depth, plainText, preservedAttrs).trimEnd()
+      return processHeading(depth, inner, plainText, slugSource, preservedAttrs).trimEnd()
     })
     // Process raw HTML <a> tags for playground link collection and URL resolution
     result = result.replace(htmlAnchorRe, (_full, beforeHref, _quote, href, afterHref, inner) => {

test/unit/server/utils/readme.spec.ts

@@ -592,6 +592,20 @@ describe('HTML output', () => {
     expect(result.html).toContain('align="center"')
   })
 
+  it('preserves inline code heading content and generates encoded slugs', async () => {
+    const markdown = ['### `<Text>`', '', '### `<Box>`'].join('\n')
+    const result = await renderReadmeHtml(markdown, 'test-pkg')
+
+    expect(result.toc).toHaveLength(2)
+    expect(result.toc[0]).toMatchObject({ text: '<Text>', id: 'user-content-lttextgt', depth: 3 })
+    expect(result.toc[1]).toMatchObject({ text: '<Box>', id: 'user-content-ltboxgt', depth: 3 })
+    expect(result.html).toContain('<code>&lt;Text&gt;</code>')
+    expect(result.html).toContain('<code>&lt;Box&gt;</code>')
+    expect(result.html).toContain('id="user-content-lttextgt"')
+    expect(result.html).toContain('id="user-content-ltboxgt"')
+    expect(result.html).not.toContain('user-content-heading')
+  })
+
   it('preserves supported attributes on rewritten raw HTML anchors (renderer.html path)', async () => {
     const md = [
       '<div>',
@@ -803,5 +817,27 @@ describe('Issue #1323 — single-pass rendering correctness', () => {
       const ids = result.toc.map(t => t.id)
       expect(new Set(ids).size).toBe(ids.length)
     })
+
+    it('keeps paragraphs and fenced code blocks when mixed with HTML headings', async () => {
+      const md = [
+        '<h2><code>&lt;Text&gt;</code></h2>',
+        '',
+        'Paragraph before code.',
+        '',
+        '```ts',
+        'const component = "Text"',
+        '```',
+        '',
+        'Paragraph after code.',
+      ].join('\n')
+
+      const result = await renderReadmeHtml(md, 'test-pkg')
+
+      expect(result.html).toContain('<code>&lt;Text&gt;</code>')
+      expect(result.html).toContain('<p>Paragraph before code.</p>')
+      expect(result.html).toContain('const component = "Text"')
+      expect(result.html).toContain('<p>Paragraph after code.</p>')
+      expect(result.html).toContain('id="user-content-lttextgt"')
+    })
   })
 })