Fix #3543 TOC sidebar scrollability for long articles

[anchalsahani]

Fixes #3543

🐞 Fix: TOC sidebar scrollability for long articles

Summary

This PR fixes an issue where the Table of Contents (TOC) sidebar was not scrollable on initial page load for long articles and only became scrollable after scrolling the main content.

As a result, TOC items below the viewport were inaccessible on first render, leading to inconsistent and confusing navigation.

---

Root cause

• The TOC container height could exceed the viewport on initial render
• Scroll behavior was applied conditionally or too late
• Scrollability depended on page scroll position instead of layout constraints

This caused the TOC to behave differently before and after scrolling the page.

---

What this PR changes

• Makes the TOC sidebar scrollable immediately on initial render
• Applies a bounded height using viewport units to prevent overflow
• Enables vertical scrolling unconditionally when content exceeds height
• Removes dependency on page scroll position for enabling scroll behavior
• Keeps TOC behavior consistent across long articles

---

Additional improvements

• Highlights the active section in the TOC while scrolling
• Automatically scrolls the TOC to keep the active section visible
• Uses IntersectionObserver for efficient scroll-spy behavior
• Avoids global CSS changes (styles are scoped to the TOC component)
• No breaking changes introduced

---

Implementation details

• The TOC container is constrained using max-height relative to the viewport
• Vertical scrolling is enabled via overflow-y: auto
• Active section tracking is handled using IntersectionObserver
• TOC auto-scroll uses scrollIntoView({ block: "nearest" })
• All changes are isolated to the TOC component

---

Expected outcome

• All TOC items are accessible immediately on page load
• Scroll behavior is consistent regardless of page scroll position
• Users can clearly track their reading position in long articles
• Improved usability and accessibility for documentation-style pages

---

Screenshots / Videos

Screen.Recording.2026-01-29.134545.mp4

---

Checklist

• Bug fix only (no feature creep)
• No breaking changes
• No global CSS changes
• Tested locally on long articles

[anchalsahani]

hi @amaan-bhati I noticed an existing PR addressing the TOC scrollbar behavior.

This PR extends that work by:

• Keeping the TOC scrollable from initial render
• Automatically scrolling the TOC to keep the active section visible
• Avoiding scrollHeight-based detection
• Scoping scrollbar styling locally (no global CSS changes)

Happy to rebase or align this with the existing PR if you’d prefer a single consolidated fix.

[anchalsahani]

Hi @Achanandhi-M I’ve fixed the build issues and pushed the updates. I’ve fixed the build issues and pushed the updates.