From 7230c54ac90e38e6080afd6ca9f6f29a01086c80 Mon Sep 17 00:00:00 2001
From: Rachael Rose Renk <91027132+rachaelrenk@users.noreply.github.com>
Date: Thu, 7 May 2026 12:00:21 -1000
Subject: [PATCH 1/2] docs: scroll active sidebar link into view on crosslink
 navigation

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>
---
 src/components/CustomSidebar.astro | 17 +++++++++++++++++
 1 file changed, 17 insertions(+)

diff --git a/src/components/CustomSidebar.astro b/src/components/CustomSidebar.astro
index 8ded00a..50f6dc1 100644
--- a/src/components/CustomSidebar.astro
+++ b/src/components/CustomSidebar.astro
@@ -33,3 +33,20 @@ import KapaLauncher from './KapaLauncher.astro';
 	<StarlightSidebarTopicsSidebar />
 </div>
 <Default><slot /></Default>
+
+<!-- Scroll the active sidebar link into view after page load.
+     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. This script
+     runs after Starlight's inline restoration (which fires synchronously
+     before DOMContentLoaded) and uses `block: 'nearest'` so it only
+     scrolls if the active item isn't already visible.
+     Desktop only — on mobile the sidebar is a drawer that scrolls
+     independently. -->
+<script is:inline>
+	(() => {
+		if (!matchMedia('(min-width: 50em)').matches) return;
+		const active = document.querySelector('.sidebar-content a[aria-current="page"]');
+		if (active) active.scrollIntoView({ block: 'nearest' });
+	})();
+</script>

From a8f371f256aa9a08954c4e8a97237bbe9a1d8ab9 Mon Sep 17 00:00:00 2001
From: Rachael Rose Renk <91027132+rachaelrenk@users.noreply.github.com>
Date: Thu, 7 May 2026 15:05:11 -1000
Subject: [PATCH 2/2] docs: center active sidebar link instead of scrolling to
 edge

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>
---
 src/components/CustomSidebar.astro | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/src/components/CustomSidebar.astro b/src/components/CustomSidebar.astro
index 50f6dc1..6068e37 100644
--- a/src/components/CustomSidebar.astro
+++ b/src/components/CustomSidebar.astro
@@ -39,14 +39,14 @@ import KapaLauncher from './KapaLauncher.astro';
      but when navigating via crosslink to a different section, the restored
      position is stale and the active link ends up off-screen. This script
      runs after Starlight's inline restoration (which fires synchronously
-     before DOMContentLoaded) and uses `block: 'nearest'` so it only
-     scrolls if the active item isn't already visible.
-     Desktop only — on mobile the sidebar is a drawer that scrolls
+     before DOMContentLoaded) and uses `block: 'center'` to place the
+     active link in the middle of the sidebar viewport for orientation.
+     Desktop only -- on mobile the sidebar is a drawer that scrolls
      independently. -->
 <script is:inline>
 	(() => {
 		if (!matchMedia('(min-width: 50em)').matches) return;
 		const active = document.querySelector('.sidebar-content a[aria-current="page"]');
-		if (active) active.scrollIntoView({ block: 'nearest' });
+	if (active) active.scrollIntoView({ block: 'center' });
 	})();
 </script>