feat: add clickable anchor links to readme headings

[essenmitsosse]

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
npmx.dev	Ready	Preview, Comment	Feb 12, 2026 0:20am

2 Skipped Deployments

Project	Deployment	Actions	Updated (UTC)
docs.npmx.dev	Ignored	Preview	Feb 12, 2026 0:20am
npmx-lunaria	Ignored		Feb 12, 2026 0:20am

[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]

📝 Walkthrough

Walkthrough

Adds CSS to render and reveal an internal hash-link indicator for README headings and preserves existing external-link styling. On the server, headings are now rendered wrapped in anchor links pointing to a generated slug (IDs remain prefixed with user-content- for page IDs), the replaceHtmlLink helper was removed, and global token-walking HTML replacements were replaced by using a marked renderer configuration. Tests updated to expect the heading text wrapped in the new anchor.

Possibly related PRs

• fix: allow all heading depths in readme and transform them #1306: Modifies heading rendering in server/utils/readme.ts, touching the same heading-to-anchor serialization logic.
• fix: markdown html links #1389: Changes README link handling and anchor/id processing across app/components/Readme.vue and server/utils/readme.ts, overlapping CSS and link-processing changes.
• fix: convert anchor links in readme content to lowercase #1296: Adjusts in-page hash link generation/formatting in server/utils/readme.ts, affecting how heading hrefs are produced.

Suggested reviewers

• danielroe
• alexdln

🚥 Pre-merge checks | ❌ 1

❌ Failed checks (1 inconclusive)

Check name	Status	Explanation	Resolution
Description check	❓ Inconclusive	The PR description consists only of a screenshot without any textual explanation of the changes, making it impossible to assess whether the description relates to the changeset.	Provide a written description explaining what changes were made and why. The description should outline the feature being added (clickable anchor links to README headings) to ensure clarity for reviewers.

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

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

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

---

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

[coderabbitai]

Actionable comments posted: 1

[essenmitsosse]

There is a still a bug for certain headings, that were luckily caught by lighthouse. I am on it.

[coderabbitai]

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

server/utils/readme.ts (1)

375-381: ⚠️ Potential issue | 🟠 Major

Preserve inline heading markup in anchor text.

Line 381 uses plainText for the anchor body, which strips inline formatting (e.g., emphasis, code spans, inline links) from headings. Use the already-rendered text for the anchor contents and keep plainText only for TOC text and slug safety.

Proposed fix

-    return `<h${semanticLevel} id="${id}" data-level="${depth}"><a href="#${uniqueSlug}">${plainText}</a></h${semanticLevel}>\n`
+    return `<h${semanticLevel} id="${id}" data-level="${depth}"><a href="#${uniqueSlug}">${text}</a></h${semanticLevel}>\n`

[whitep4nth3r]

Just marking as draft as it's not ready yet and a couple of us are going down the list to see what we can review!

[essenmitsosse]

@whitep4nth3r it is ready now.

[whitep4nth3r]

Couple of things. I tested on mobile.

1. When you click on a link, the top of the section scrolls out of view.
2. Can you make the full heading clickable? Especially on mobile it's hard to know it's clickable, and it would make it easier to click rather than just clicking on the small icon on the left. (It's not obvious but I was trying to click on the headings.)

trim.DB6685A2-F41D-4DD3-AD40-6D5367FE0082.MOV

[danielroe]

When you click on a link, the top of the section scrolls out of view.

we probably need to add scroll margin if you haven't already

[danielroe]

honestly I thought this had already been done (including scroll-margin!) - maybe it was somehow reverted.

[knowler]

A couple of thoughts:

1. Should the link icon be always visible on mobile? It’s not totally clear that there are links there.
2. It is possible for a README to already have a link in a heading (e.g. ## A [link](https://example.com) in a heading) which means there could be nested links. So, that could be a reason to avoid making the entire heading clickable, though I do like the idea of doing something to increase the touch target size.

[essenmitsosse]

@knowler

1. Id be fine with that. Shall in update?
2. yes that is in theory possible. Nuxt for example has links in the headings. But without href 🤷‍♂️ they are pretty broken on GitHub as well. Otherwise I'd say let's copy GitHub's and/or npmjs.com behavior because that is what people will be testing against.

[essenmitsosse]

Ok. Let's not copy npmsjs. This is completely broken: https://www.npmjs.com/package/nuxt#local-development

[essenmitsosse]

@whitep4nth3r
The full heading should be clickable.

I created an issue #1428 for the scroll margin problem because that also affects other things (like toc) and I have no idea why it is not working.

[essenmitsosse]

I think GitHub does it fine:

Anchor is before the heading, always visible on mobile and if the heading has a link only the anchor is clickable.

Good example: https://github.com/facebook/react

[knowler]

In #1417 (comment), @essenmitsosse said,

Anchor is before the heading, always visible on mobile and if the heading has a link only the anchor is clickable.

In the React GitHub example, the full heading is never clickable though.

Visually, it’d be fine to put the anchor before, but for assistive tech discoverability (e.g. navigating by heading), it would be good to place it after in the DOM (GitHub also does this). This is an exception to the DOM order matches visual order rule.

In #1417 (comment), @essenmitsosse said,

yes that is in theory possible. Nuxt for example has links in the headings. But without href 🤷‍♂️ they are pretty broken on GitHub as well. Otherwise I'd say let's copy GitHub's and/or npmjs.com behavior because that is what people will be testing against.

Nuxt README is using an old school technique. I’m less worried for the <a> without href cases because they don’t implicitly get the link role.

It could be ok if we strip out the <a> elements, but I could see some cases where they serve a purpose. The React README example would be perfect… if they included that one in the package (i.e. it looks like they swap it out for a more package focused one).

[essenmitsosse]

I honestly struggle to find any package that has links in their readme heading. Would it be too farfetched to assume that is not a feature we need to support or should we support it just because it is possible?

If we ingore this case, I think the anchor after the heading is fine. It also makes it less tricky to place it on mobile without having to much spacing or indenting the headings.

In which case I would assume the current version is good enough for now?