fix: hard-code scroll margin per-page to account for fixed header size

[WilcoSp]

When using table of content the scroll behaviour caused that the scrolled to element to be underneath the header(s). I've now added scroll margin to the scroll behaviour so that scrolled to element isn't any more underneath the header(s).

by default the margin is 70 but it's possible with definePageMeta to set a different scroll margin, at least right now the package, code & docs pages have different scroll margins due to their additional headers.

before:
->

after:
->

---

this will fix #1428 & fix #1518

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
npmx.dev	Ready	Preview, Comment	Feb 22, 2026 10:16pm

2 Skipped Deployments

Project	Deployment	Actions	Updated (UTC)
docs.npmx.dev	Ignored	Preview	Feb 22, 2026 10:16pm
npmx-lunaria	Ignored		Feb 22, 2026 10:16pm

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

---

📝 Walkthrough

Walkthrough

This pull request introduces a scrolling offset feature to address anchor links being hidden behind sticky headers. The changes add a scrollMargin property to page metadata across multiple route files with varying offsets (150–180 pixels). The router's scroll behaviour is enhanced to read this metadata and apply the offset when scrolling to hash-based anchors. A new optional scrollMargin property is added to the PageMeta type interface with a default value of 70 pixels. The router now preserves saved scroll positions and implements smooth scrolling with the configured margins.

Possibly related PRs

• feat: use native scroll anchoring #1209: Modifies in-page anchor scrolling behaviour to enable native smooth scrolling alongside programmatic scroll control.
• refactor: add proper route segments for package code #1301: Refactors package-code route parameters and URL builders on the same page being modified in this PR.

Suggested reviewers

• danielroe

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description check	✅ Passed	The PR description clearly explains the scroll margin implementation to prevent headers overlapping anchored content, detailing default and custom values.
Linked Issues check	✅ Passed	The changes successfully implement scroll margin functionality to prevent anchor links from scrolling behind sticky headers, addressing issue #1428 requirements.
Out of Scope Changes check	✅ Passed	All changes are directly related to implementing scroll margin behaviour for anchor navigation, with no extraneous modifications detected.

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

✨ Finishing Touches

• 📝 Generate docstrings (stacked PR)
• 📝 Generate docstrings (commit on current branch)

🧪 Generate unit tests (beta)

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

Tip

Issue Planner is now in beta. Read the docs and try it out! Share your feedback on Discord.

---

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.}

[codecov]

Codecov Report

❌ Patch coverage is 0% with 3 lines in your changes missing coverage. Please review.
✅ All tests successful. No failed tests found.

Files with missing lines	Patch %	Lines
app/router.options.ts	0.00%	3 Missing ⚠️

📢 Thoughts on this report? Let us know!

[coderabbitai]

Actionable comments posted: 1

[coderabbitai]

⚠️ Potential issue | 🟡 Minor

🧩 Analysis chain

🏁 Script executed:

# Check the actual file and verify line 10 content
cat -n app/pages/package-docs/[...path].vue | head -20

Repository: npmx-dev/npmx.dev

Length of output: 781

---

🏁 Script executed:

# Check router.options.ts implementation
fd 'router.options.ts' --exec cat {} \;

Repository: npmx-dev/npmx.dev

Length of output: 680

---

🏁 Script executed:

# Verify CSS values in the Vue component, specifically around lines 273-275
cat -n app/pages/package-docs/[...path].vue | sed -n '270,280p'

Repository: npmx-dev/npmx.dev

Length of output: 379

---

🏁 Script executed:

# Search for scroll-related CSS or scroll-mt values in the file
rg 'scroll-m|scroll-margin' app/pages/package-docs/[...path].vue

Repository: npmx-dev/npmx.dev

Length of output: 83

---

Align scrollMargin: 180 with CSS scroll-mt-32 (128 px) for consistent scroll positioning

Direct URL navigation with a hash anchor applies the CSS scroll-mt-32 rule (128 px), whereas router-driven navigation (e.g., clicking a TOC link) uses the scrollMargin: 180 offset. This 52 px difference results in inconsistent scroll positions depending on the navigation path, affecting user experience. Align both values to ensure the symbol lands at the same vertical position regardless of how the user reaches it.

[github-actions]

Thanks for your first contribution, @WilcoSp! 👏

We'd love to welcome you to the npmx community. Come and say hi on Discord! And once you've joined, visit npmx.wamellow.com to claim the contributor role.