From a89e54cb4d3e4ef8f3f3f8af0fd2d0f150255b11 Mon Sep 17 00:00:00 2001
From: Vordgi <sasha2822222@gmail.com>
Date: Sun, 12 Apr 2026 12:34:48 +0100
Subject: [PATCH 1/3] fix: improve anchors parsing in readmes

---
 app/pages/package/[[org]]/[name].vue |  1 -
 server/utils/readme.ts               | 16 +++++++++++++++-
 2 files changed, 15 insertions(+), 2 deletions(-)

diff --git a/app/pages/package/[[org]]/[name].vue b/app/pages/package/[[org]]/[name].vue
index bc10db6210..b9740f799f 100644
--- a/app/pages/package/[[org]]/[name].vue
+++ b/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"
       />
diff --git a/server/utils/readme.ts b/server/utils/readme.ts
index a97e620ebd..e3939fb4af 100644
--- a/server/utils/readme.ts
+++ b/server/utils/readme.ts
@@ -549,11 +549,23 @@ export async function renderReadmeHtml(
       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`
   }
 
   renderer.heading = function ({ tokens, depth }: Tokens.Heading) {
-    const displayHtml = this.parser.parseInline(tokens)
+    const anchorTokenRegex = /^<a(\s.+)?\/?>$/
+    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 @@ ${html}
 
     const { resolvedHref, extraAttrs } = processLink(href, plainText || title || '')
 
+    if (!resolvedHref) return text
+
     return `<a href="${resolvedHref}"${titleAttr}${extraAttrs}>${text}</a>`
   }
 

From 9fdbec4d0fa8b073c5d898c5d8213179a42b61a1 Mon Sep 17 00:00:00 2001
From: Vordgi <sasha2822222@gmail.com>
Date: Sun, 12 Apr 2026 22:05:35 +0100
Subject: [PATCH 2/3] chore: reuse regex in renderer heading

---
 server/utils/readme.ts | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/server/utils/readme.ts b/server/utils/readme.ts
index e3939fb4af..81dddfbb28 100644
--- a/server/utils/readme.ts
+++ b/server/utils/readme.ts
@@ -558,8 +558,8 @@ export async function renderReadmeHtml(
     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 anchorTokenRegex = /^<a(\s.+)?\/?>$/
     const isAnchorHeading =
       anchorTokenRegex.test(tokens[0]?.raw ?? '') && tokens[tokens.length - 1]?.raw === '</a>'
 

From 859e9a49d311424f1b2075de72a0c973fbfbbcea Mon Sep 17 00:00:00 2001
From: Vordgi <sasha2822222@gmail.com>
Date: Sun, 12 Apr 2026 22:06:10 +0100
Subject: [PATCH 3/3] test: cover links in renderer heading

---
 test/unit/server/utils/readme.spec.ts | 34 +++++++++++++++++++++++++++
 1 file changed, 34 insertions(+)

diff --git a/test/unit/server/utils/readme.spec.ts b/test/unit/server/utils/readme.spec.ts
index 5d85902158..dacc2653b7 100644
--- a/test/unit/server/utils/readme.spec.ts
+++ b/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')