fix: improve anchors parsing in readmes

app/pages/package/[[org]]/[name].vue

@@ -548,7 +548,6 @@ const showSkeleton = shallowRef(false)
         :latest-version="latestVersion"
         :provenance-data="provenanceData"
         :provenance-status="provenanceStatus"
-        :class="$style.areaHeader"
         page="main"
         :version-url-pattern="versionUrlPattern"
       />

server/utils/readme.ts

@@ -549,11 +549,23 @@
       toc.push({ text: plainText, id, depth })
     }
 
+    // The browser doesn't support anchors within anchors and automatically extracts them from each other,
+    // causing a hydration error. To prevent this from happening in such cases, we use the anchor separately
+    if (htmlAnchorRe.test(displayHtml)) {
+      return `<h${semanticLevel} id="${id}" data-level="${depth}"${preservedAttrs}>${displayHtml}<a href="#${id}"></a></h${semanticLevel}>\n`
+    }
+
     return `<h${semanticLevel} id="${id}" data-level="${depth}"${preservedAttrs}><a href="#${id}">${displayHtml}</a></h${semanticLevel}>\n`
   }
 
+  const anchorTokenRegex = /^<a(\s.+)?\/?>$/
   renderer.heading = function ({ tokens, depth }: Tokens.Heading) {
-    const displayHtml = this.parser.parseInline(tokens)
+    const isAnchorHeading =
+      anchorTokenRegex.test(tokens[0]?.raw ?? '') && tokens[tokens.length - 1]?.raw === '</a>'
+
+    // for anchor headings, we will ignore user-added id and add our own
+    const tokensWithoutAnchor = isAnchorHeading ? tokens.slice(1, -1) : tokens
+    const displayHtml = this.parser.parseInline(tokensWithoutAnchor)
     const plainText = getHeadingPlainText(displayHtml)
     const slugSource = getHeadingSlugSource(displayHtml)
     return processHeading(depth, displayHtml, plainText, slugSource)
@@ -643,6 +655,8 @@
 
     const { resolvedHref, extraAttrs } = processLink(href, plainText || title || '')
 
+    if (!resolvedHref) return text
+
     return `<a href="${resolvedHref}"${titleAttr}${extraAttrs}>${text}</a>`
   }
 

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

@@ -591,6 +591,40 @@ describe('HTML output', () => {
     expect(result.html).toContain('id="user-content-api-1"')
   })
 
+  describe('heading anchors (renderer.heading)', () => {
+    it('strips a full-line anchor wrapper and uses inner text for slug, toc, and permalink', async () => {
+      const markdown = '## <a href="https://example.com">My Section</a>'
+      const result = await renderReadmeHtml(markdown, 'test-pkg')
+
+      expect(result.toc).toEqual([{ text: 'My Section', depth: 2, id: 'user-content-my-section' }])
+      expect(result.html).toBe(
+        `<h3 id="user-content-my-section" data-level="2"><a href="#user-content-my-section">My Section</a></h3>\n`,
+      )
+    })
+
+    it('uses a trailing empty permalink when heading content already includes a link (no nested anchors)', async () => {
+      const markdown = '### See <a href="https://example.com">docs</a> for more'
+      const result = await renderReadmeHtml(markdown, 'test-pkg')
+
+      expect(result.toc).toEqual([
+        { text: 'See docs for more', depth: 3, id: 'user-content-see-docs-for-more' },
+      ])
+      expect(result.html).toBe(
+        `<h3 id="user-content-see-docs-for-more" data-level="3">See <a href="https://example.com" rel="nofollow noreferrer noopener" target="_blank">docs</a> for more<a href="#user-content-see-docs-for-more"></a></h3>\n`,
+      )
+    })
+
+    it('applies the same permalink pattern to raw HTML headings that contain links', async () => {
+      const md = '<h2>Guide: <a href="https://example.com/page">page</a></h2>'
+      const result = await renderReadmeHtml(md, 'test-pkg')
+
+      expect(result.toc).toEqual([{ text: 'Guide: page', depth: 2, id: 'user-content-guide-page' }])
+      expect(result.html).toBe(
+        '<h3 id="user-content-guide-page" data-level="2">Guide: <a href="https://example.com/page" rel="nofollow noreferrer noopener" target="_blank">page</a><a href="#user-content-guide-page"></a></h3>',
+      )
+    })
+  })
+
   it('preserves supported attributes on raw HTML headings', async () => {
     const md = '<h1 align="center">My Package</h1>'
     const result = await renderReadmeHtml(md, 'test-pkg')