From 33824e1f3238dd47b8d2c8a13e1132a229da4a31 Mon Sep 17 00:00:00 2001 From: Felix Stubner Date: Fri, 28 Aug 2026 14:57:46 +0100 Subject: [PATCH 1/2] Put the docs contents list back in the right-hand rail It was moved out of the rail and under the hero, and it should not have been. The feedback that prompted the move was about the NARROW list not collapsing into a dropdown; collapsing the narrow one was right, moving the wide one was not, and the two got done together. Starlight already does exactly what was wanted -- rail on desktop, collapsed dropdown below -- so this is a revert rather than a redesign. The MarkdownContent override existed only to render the list under the hero and is gone; PageSidebar renders the rail again beside the dropdown it already had; and 30-toc-under-hero.css keeps only the one unrelated rule it had picked up, for the search dialog's offline message. Measured at both ends. At 1790px the list sits at x=1425, right of a content column ending at 1407, with the dropdown hidden. At 375px the dropdown is back, collapsed, with the rail hidden. No horizontal overflow at either. Not touched here, but found while looking: 12-docs-toc-responsive.css contains three occurrences of a closing brace and the next selector on one line (`}.right-sidebar {`). It is valid CSS and predates this change, but it is why an automated pass over that file could not match its rules. --- site/astro.config.mjs | 1 - .../starlight/MarkdownContent.astro | 61 ------------- .../components/starlight/PageSidebar.astro | 15 +++- .../styles/starlight/30-toc-under-hero.css | 85 ++----------------- 4 files changed, 18 insertions(+), 144 deletions(-) delete mode 100644 site/src/components/starlight/MarkdownContent.astro diff --git a/site/astro.config.mjs b/site/astro.config.mjs index 6bb18dd4..e19f6cf1 100644 --- a/site/astro.config.mjs +++ b/site/astro.config.mjs @@ -46,7 +46,6 @@ export default defineConfig({ Footer: './src/components/starlight/Footer.astro', MobileMenuFooter: './src/components/starlight/MobileMenuFooter.astro', PageSidebar: './src/components/starlight/PageSidebar.astro', - MarkdownContent: './src/components/starlight/MarkdownContent.astro', }, // Split from a single 4,965-line starlight.css into ordered per-pass // files (see docs/ARCHITECTURE.md). Order matters: several later diff --git a/site/src/components/starlight/MarkdownContent.astro b/site/src/components/starlight/MarkdownContent.astro deleted file mode 100644 index ad3b92d3..00000000 --- a/site/src/components/starlight/MarkdownContent.astro +++ /dev/null @@ -1,61 +0,0 @@ ---- -/** - * Article content, with the table of contents above it. - * - * Starlight puts the ToC in a fixed right-hand rail (`TwoColumnContent.astro`) - * at >=72rem, and collapses it to a dropdown below that. This override keeps - * the dropdown for narrow screens and moves the wide-screen version into the - * content column, directly under the hero band. - * - * Which of the two shows is decided in styles/starlight/30-toc-under-hero.css, - * at the same 50rem breakpoint the left sidebar uses -- not by Starlight's - * 72rem utility classes. Keyed to 72rem, the 50-72rem band showed the - * collapsed dropdown next to a fully expanded sidebar, which read as the ToC - * having collapsed for no reason. - * - * It hangs off MarkdownContent rather than PageTitle: PageTitle renders - * inside the hero's own panel, so the list ended up overlapping the title - * inside the gradient band. This slot is the first thing in the content - * column below it. - * - * The `.right-sidebar-panel` class is kept deliberately even though this is - * no longer the right sidebar -- every rail, marker, hover and theme rule in - * the 29-file override stack is keyed on it, and re-homing all of them is the - * kind of change that stack makes risky. It now reads as a component name; - * `docs-toc-under-hero` carries the layout. - */ -import TableOfContents from 'virtual:starlight/components/TableOfContents'; - -const { toc } = Astro.locals.starlightRoute; ---- - -{ - toc && ( -
- -
- ) -} - -
- - diff --git a/site/src/components/starlight/PageSidebar.astro b/site/src/components/starlight/PageSidebar.astro index e6f247f5..08481d13 100644 --- a/site/src/components/starlight/PageSidebar.astro +++ b/site/src/components/starlight/PageSidebar.astro @@ -1,5 +1,6 @@ --- import MobileTableOfContents from 'virtual:starlight/components/MobileTableOfContents'; +import TableOfContents from 'virtual:starlight/components/TableOfContents'; const { sidebar: routeSidebar, toc } = Astro.locals.starlightRoute; const sidebar = routeSidebar as SidebarEntry[]; @@ -104,9 +105,17 @@ const currentGroupLabel = formatCrumb(currentGroup?.label) || 'Start'; { toc && ( <> - {/* Narrow screens keep the collapsed dropdown. The wide-screen list - moved to PageTitle.astro so it sits under the hero rather than in - the right-hand rail. */} + {/* Wide screens: the contents list in the right-hand rail, which is + where Starlight puts it and where a reader looks for it. It was + briefly moved under the hero; that came from feedback about the + NARROW list not collapsing, and moving the wide one was not the + fix for it. */} +
+
+ +
+
+ {/* Narrow screens keep the collapsed dropdown. */}
diff --git a/site/src/styles/starlight/30-toc-under-hero.css b/site/src/styles/starlight/30-toc-under-hero.css index b6bfdc29..618f0bf4 100644 --- a/site/src/styles/starlight/30-toc-under-hero.css +++ b/site/src/styles/starlight/30-toc-under-hero.css @@ -1,85 +1,12 @@ -/* Contents list under the hero, instead of in the right-hand rail. +/* Leftovers from the contents-list experiment that moved the ToC out of + * the right-hand rail and under the hero. That is reverted: Starlight puts + * the ToC in the rail on desktop and collapses it to a dropdown below, + * which is what was wanted -- the original complaint was that the MOBILE + * list was not collapsing, and moving the desktop one was not the fix. * - * The list is rendered by src/components/starlight/MarkdownContent.astro; see - * that file for why it keeps the `.right-sidebar-panel` class. These rules - * undo the parts of that class that only made sense in a fixed 208px rail. + * Only this one unrelated rule is still needed here. */ -/* Which of the two contents lists shows, and where the switch happens. - * - * 50rem, the width at which the left sidebar stops being a drawer and becomes - * a permanent column. Starlight's own switch for the ToC is 72rem, so the - * 50-72rem band showed the collapsed dropdown beside a fully expanded - * sidebar, with a strip of empty hero above it -- one of the two navigation - * panes collapsed and the other not, at a width with room for both. */ -@media (max-width: 49.99rem) { - .docs-toc-under-hero { - display: none !important; - } -} - -@media (min-width: 50rem) { - .docs-toc-under-hero { - display: block !important; - } - - mobile-starlight-toc { - display: none !important; - } -} - -/* The column Starlight reserves for the rail has to collapse, or the article - keeps a dead gutter roughly a sidebar wide. TwoColumnContent.astro sizes - .main-pane by subtracting that width, so both change together. */ -@media (min-width: 72rem) { - .right-sidebar-container { - display: none !important; - } - - [data-has-sidebar][data-has-toc] .main-pane, - .main-pane { - width: 100% !important; - } -} - -/* Full content width, not the rail's 208px -- otherwise the multi-column - rule below can only ever produce one column. */ -.docs-toc-under-hero.right-sidebar-panel { - width: 100% !important; - max-width: none !important; - padding: 0 !important; -} - -.docs-toc-under-hero .sl-container { - width: auto !important; - max-width: none !important; -} - -/* The rail moves from the list onto each link. In the rail layout a single - border on the