Add autoscroll to TOC
What does this MR do and why?
If the table of contents on the right side of the page extends beyond the viewport, the user can't see TOC highlighting once they start scrolling down the page beyond the visible portion of the TOC.
To keep the user oriented in relation to the TOC, this MR adds autoscrolling to the TOC. If the active heading is below the viewport, the TOC scrolls up to keep the active heading visible.
If the user's prefersReducedMotion setting is on, the scrolling happens instantly. Otherwise, the scrolling is smooth.
Acceptance criteria
- On a page with a long TOC (e.g., http://localhost:1313/ci/yaml/), as you scroll down the page, when the active heading is at the bottom of the page, the TOC will scroll up so that the active heading is visible. Similarly, as you scroll back up, when the active header is at the top of the screen, the TOC will scroll down.
- As before, when you click an item on the TOC, the page content should scroll to the active heading. The heading you clicked should be the active heading.
- In either case above, the scrolling should be smooth by default and instant if the user prefers reduced motion.
Screenshots, screen recordings, or links to review app
| with banner | with reduced motion |
|---|---|
| Screen_Recording_2025-12-01_at_8.54.44_AM | Screen_Recording_2025-12-01_at_9.00.17_AM |
How to set up and validate locally
Numbered steps to set up and validate the change are strongly suggested.
- Configure a local GitLab Docs environment.
- Check out this branch or view the review app.
- On a page with a long TOC, scroll the content up and down to verify that the active heading remains visible.
- Click on a heading in the TOC and verify that the heading you clicked becomes bold and the page scrolls to the corresponding heading in the content.
- Turn on prefersReducedMotion (system settings -> accessibility -> motion -> reduce motion) and verify that the scrolling is instant rather than smooth.
Merge request acceptance checklist
This checklist encourages us to confirm any changes have been analyzed to reduce risks in quality, performance, reliability, security, and maintainability.
-
I have evaluated the MR acceptance checklist for this merge request.
Closes #430 (closed)