feat(#1932): implement smooth scrolling for anchor navigation across site

[Mohit5Upadhyay]

Description

This PR implements smooth scrolling for in-page navigation across the Express.js website as mentioned in Issue : #1932

This improves the user experience by ensuring that navigation to sections via anchor links transitions smoothly, rather than jumping abruptly.

Closes #1932

Video

smooth-scrolling.mp4

[netlify]

✅ Deploy Preview for expressjscom-preview ready!

Name	Link
🔨 Latest commit	736831c
🔍 Latest deploy log	https://app.netlify.com/projects/expressjscom-preview/deploys/687284c4ba7dd4000809c1fc
😎 Deploy Preview	https://deploy-preview-1965--expressjscom-preview.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[ShubhamOulkar]

Can you please remove this line https://github.com/expressjs/expressjs.com/blob/gh-pages/js/menu.js#L186 ? Since default behavior stopped here.

[ShubhamOulkar]

Suggested change

	$(document).on('click', 'a[href^="#"]:not([href="#"]):not([href="#top"])', function(e) {
	$("#api-doc").on('click', 'a[href^="#"]:not([href="#"]):not([href="#top"])', function(e) {

We should minimize the scope of this click event. Currently, $(document).on('click'...) attaches the handler to all anchor links with # across every page. However, smooth scrolling is only needed on API pages, since the TOC exists only there. Scoping it to #api-doc avoids unnecessary event handling and prevents inconsistent anchor # behavior on other pages. Also, checking "#api-doc" exist on page is required before applying click event.

[bjohansebas]

Thanks for the PR!

As i mentioned in the issue, this can be handled through CSS, javascript is not necessary.

[ShubhamOulkar]

this can be handled through CSS,

I am OK with CSS only solution. But this approach comes with some limitations, like we cannot control scroll behavior and can not add header offsets. But it is fine if headings are not hiding behind the header bar on anchor link click.

[Mohit5Upadhyay]

Thanks @bjohansebas for the suggestion about a CSS-only solution!
Unfortunately, I think for this project, CSS alone isn’t sufficient because:

• IDs like #app.METHOD (http://localhost:4000/en/5x/api.html#app.listen) contain dots, which CSS can’t reliably scroll to without custom JS.
• We need a precise scroll offset (120px) to avoid headings hiding behind the navbar.

So I’d propose keeping the JS smooth scroll, scoped only to #api-doc to avoid global impact as per suggested by @ShubhamOulkar.

Let me know if you’d prefer another approach!
Thanks again for your feedback.

[bjohansebas]

But it is fine if headings are not hiding behind the header bar on anchor link click.

The headings are never hidden by the header bar, or at least I’ve been trying to reproduce it and haven’t been able to.

IDs like #app.METHOD (http://localhost:4000/en/5x/api.html#app.listen) contain dots, which CSS can’t reliably scroll to without custom JS.

That doesn’t matter in CSS, since the effect will be applied to all elements anyway.

* {
  scroll-behavior: smooth;
}

[Mohit5Upadhyay]

Hi @bjohansebas and @ShubhamOulkar,

I’ve updated the implementation to follow your suggestion of a CSS-only smooth scrolling solution.

• I removed all the custom JavaScript smooth scroll code I previously added.
• Instead, I’ve applied this in CSS:

* {
  scroll-behavior: smooth;
}

h1, h2, h3, h4, h5, h6,
[id] {
  scroll-margin-top: 120px;
}

@media (prefers-reduced-motion: reduce) {
  html {
    scroll-behavior: auto;
  }
}

Let me know if you’d like any further changes!
Thanks for your time! 🙏