fix: change readme md renderer behavior

[RYGRIT]

🔗 Linked issue

resolves #1323

🧭 Context

📚 Description

This PR fixes README rendering issues caused by split processing between marked and sanitizeHtml, and makes heading/link handling more consistent in mixed markdown + raw HTML content.

What changed:

• Processed headings and links in a more consistent single-pass flow during marked rendering.
• Fixed TOC/slug ordering for mixed markdown and raw HTML headings.
• Prevented heading ID collisions when heading text already includes user-content-.
• Preserved supported attributes during raw HTML rewrites:
  • headings keep supported attrs (e.g. align)
  • anchors preserve allowlisted attrs (including title, even when placed before href)
  • rewritten anchors normalize href and enforce safe rel/target without duplicates
• Added/updated unit tests for mixed heading order, duplicate slug/ID behavior, and raw HTML anchor/heading attribute preservation (including renderer.html-path cases).

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
npmx.dev	Ready	Preview, Comment	Mar 2, 2026 1:12am

2 Skipped Deployments

Project	Deployment	Actions	Updated (UTC)
docs.npmx.dev	Ignored	Preview	Mar 2, 2026 1:12am
npmx-lunaria	Ignored		Mar 2, 2026 1:12am

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ All tests successful. No failed tests found.

📢 Thoughts on this report? Let us know!

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between dcda67f and 8f8e3c0.

📒 Files selected for processing (1)

• server/utils/readme.ts

---

📝 Walkthrough

Walkthrough

Refactors README rendering into a single-pass pipeline. Adds user-content prefixing utilities (USER_CONTENT_PREFIX, withUserContentPrefix, toUserContentId, toUserContentHash) and normalizePreservedAnchorAttrs. Centralises heading processing (semantic level, slug generation, TOC collection) and unifies Markdown+HTML heading handling so IDs use user-content prefixes. Consolidates URL resolution, playground-link collection, and security attribute application via processLink/resolveUrl with seenUrls de-duplication. Renderer changes intercept raw HTML headings and anchors, normalize attributes, and ensure idempotent anchor/hash handling. Tests expanded to validate TOC ordering, slug collisions, ID consistency, link resolution and single-pass behaviour.

Possibly related PRs

• fix: readme rendering result lacks anchor point jump #994: Also modifies server/utils/readme.ts to apply universal id-prefixing and restore hash-jump behaviour; overlaps on id/anchor handling and transformTags.
• feat: replace links in markdown instead of via javascript #1339: Changes resolveUrl and link-processing logic in server/utils/readme.ts; directly related to the consolidated URL resolution here.
• fix: markdown html links #1389: Unifies link/HTML and Markdown processing (single-pass sanitization, playground detection, URL resolution) in server/utils/readme.ts and overlaps significantly with this refactor.

Suggested reviewers

• danielroe
• alexdln

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description check	✅ Passed	The PR description clearly relates to the changeset, detailing fixes for README rendering issues with single-pass processing, TOC ordering, heading ID collisions, and attribute preservation.
Linked Issues check	✅ Passed	The PR implements all core objectives from issue #1323: single-pass processing, corrected TOC ordering, heading ID collision prevention, link detection from raw HTML, and consolidation of link/slug handling.
Out of Scope Changes check	✅ Passed	All changes are directly aligned with issue #1323 objectives. The refactoring of renderReadmeHtml, link processing, and test additions focus exclusively on single-pass rendering and mixed heading handling.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 4

🧹 Nitpick comments (1)

test/unit/server/utils/readme.spec.ts (1)

579-584: Add a regression case for user-content- slug collisions.

This duplicate-slug test only covers identical heading text. Please add a case like # Title plus # user-content-title to ensure generated IDs remain unique.

🧪 Suggested additional test

   it('handles duplicate raw HTML heading slugs', async () => {
     const md = '<h2>API</h2>\n\n<h2>API</h2>'
     const result = await renderReadmeHtml(md, 'test-pkg')
     expect(result.html).toContain('id="user-content-api"')
     expect(result.html).toContain('id="user-content-api-1"')
   })
+
+  it('keeps IDs unique when a heading slug already starts with user-content-', async () => {
+    const md = '# Title\n\n# user-content-title'
+    const result = await renderReadmeHtml(md, 'test-pkg')
+    const ids = result.toc.map(t => t.id)
+    expect(new Set(ids).size).toBe(ids.length)
+  })
 })

---

ℹ️ Review info

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between f18d64e and a4d07f7.

📒 Files selected for processing (2)

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

[coderabbitai]

Actionable comments posted: 1

---

ℹ️ Review info

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between a4d07f7 and dcda67f.

📒 Files selected for processing (2)

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