docs: scroll active sidebar link into view on crosslink navigation#34
Merged
rachaelrenk merged 3 commits intomainfrom May 8, 2026
Merged
docs: scroll active sidebar link into view on crosslink navigation#34rachaelrenk merged 3 commits intomainfrom
rachaelrenk merged 3 commits intomainfrom
Conversation
After page load, call scrollIntoView({ block: 'nearest' }) on the
active sidebar link. Starlight's SidebarPersister restores scrollTop
from sessionStorage, but when navigating via crosslink to a different
section, the restored position is stale and the active link ends up
off-screen. block:'nearest' ensures we only scroll if the item isn't
already visible. Desktop only (min-width: 50em).
Co-Authored-By: Oz <oz-agent@warp.dev>
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
hongyi-chen
approved these changes
May 8, 2026
Collaborator
hongyi-chen
left a comment
hongyi-chen
left a comment
There was a problem hiding this comment.
Approving, but is there any way to make the location that we scroll to on the crosslinked page a bit more centered? e.g. I clicked code editor here, and I navigated to the linked page, but on the lefthand nav bar, the page is at the very bottom. Would be nice if it was up a bit more! lmk if that doesn't make sense
Change scrollIntoView from block:'nearest' to block:'center' so the active link appears in the middle of the sidebar viewport rather than at the bottom edge. Better for orientation. Co-Authored-By: Oz <oz-agent@warp.dev>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Scroll the active sidebar link into view when navigating via crosslink to a page in a different section of the sidebar.
Problem
When navigating via crosslink, Starlight correctly highlights the destination page with
aria-current="page"in the sidebar, but the sidebar doesn't scroll to that item. Starlight'sSidebarPersisterrestoresscrollTopfromsessionStorage, which is stale after a crosslink -- the user lands on the correct page but the sidebar shows a different section, causing disorientation.Fix
Added an inline script to
CustomSidebar.astrothat callsscrollIntoView({ block: 'nearest' })on the active sidebar link after page load. The script:block: 'nearest'so it only scrolls if the active item isn't already visible (avoids fighting Starlight's restoration when it works correctly)min-width: 50em) -- mobile sidebar is a drawer that scrolls independentlyContext
Part of the docs v2 bug bash follow-up work. Tracks to Notion item: Migration FF: sidebar scroll-to-active on crosslink.
Co-Authored-By: Oz oz-agent@warp.dev