From 2778a3e6109409217393d194106a42eb2153b9b4 Mon Sep 17 00:00:00 2001
From: Kieron Lanning <kieronlanning@users.noreply.github.com>
Date: Tue, 3 Nov 2026 18:36:30 +0000
Subject: [PATCH] fix(docs): keep one sidebar entry per project; versions live
 in the switcher

The sidebar had become one topic per documentation version, so a project with live and prerelease docs appeared twice and the topic list read as a flat set of versions. Each channel still contributes its own topic internally (the page list must match the version being read), but every topic now carries the project name and the picker collapses the duplicates. Versions appear only in the page switcher, which is shown only while two versions are published.
---
 AGENTS.md                                     |  6 ++--
 README.md                                     | 12 ++++----
 docs/decisions/0009-documentation-channels.md | 12 ++++----
 .../components/starlight/TopicSelect.astro    | 16 ++++++++++-
 src/src/lib/docs/channels.ts                  | 12 ++++----
 src/src/lib/docs/sidebar.ts                   | 18 ++++++------
 src/src/pages/docs/index.astro                |  5 ++--
 src/tests/dist/built-output.test.ts           | 28 +++++++++++++------
 src/tests/unit/docs-sidebar.test.ts           | 17 +++++++----
 9 files changed, 79 insertions(+), 47 deletions(-)

diff --git a/AGENTS.md b/AGENTS.md
index 552ab6f..6248a71 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -87,9 +87,9 @@ prints advisory observations (which never fail the build) when a project's decla
      pin a project's live and prerelease documentation to refs (`default`, `latest-stable`,
      `latest-prerelease`, or an explicit branch/tag). The default channel owns `/docs/<id>/`, the
      other is served at `/docs/<id>/<channel>/`, and `docsPage` resolves against the default channel.
-     Each channel is a first-class docs set — its own sidebar topic (`<Project> <version>`), its own
-     `/projects/<id>/<channel>/llms*.txt` bundle, and its own entry on the docs portal — because the
-     same product at another version is different documentation.
+     Each channel is a first-class docs set — its own page list (the sidebar lists the project once
+     but follows the version being read), its own `/projects/<id>/<channel>/llms*.txt` bundle, and
+     its own entry on the docs portal. The page switcher, not the sidebar, chooses the version.
      Only `github-path` supports two channels; `wiki`/`readme` have a single version. Promotion is
      automatic: the prerelease channel is withheld once a stable release (GitHub release or NuGet
      version) catches up with the prerelease line, and returns with the next prerelease — never
diff --git a/README.md b/README.md
index 0724716..33276e2 100644
--- a/README.md
+++ b/README.md
@@ -317,11 +317,13 @@ docs:
 
 The `live` channel is the default and keeps the canonical `/docs/<project>/`
 URLs; the `prerelease` channel is served at `/docs/<project>/prerelease/`.
-Versions are first-class: each published channel is its own sidebar topic
-(`ZodSharp 2.4.2`, `ZodSharp 3.0.0-prerelease.2`) with its own page list, its
-own machine-readable bundle, and its own entry on the documentation portal —
-same product, different version, therefore different docs. Every page also
-offers a switcher. Only `github-path` sources support two channels.
+Versions are first-class: each published version has its own page list, its own
+machine-readable bundle, and its own entry on the documentation portal — same
+product, different version, therefore different docs. The sidebar stays
+hierarchical, with one entry per project, and its page list follows the version
+you are reading. The version itself appears only in the page switcher, which is
+shown while two versions are published and names both. Only `github-path`
+sources support two channels.
 
 **Promotion is automatic.** The build publishes the prerelease channel only
 while a prerelease version outranks the newest stable release — comparing GitHub
diff --git a/docs/decisions/0009-documentation-channels.md b/docs/decisions/0009-documentation-channels.md
index dd52263..470a0de 100644
--- a/docs/decisions/0009-documentation-channels.md
+++ b/docs/decisions/0009-documentation-channels.md
@@ -149,12 +149,12 @@ history has to survive between builds, and an existing page is never overwritten
   while two channels are published: promotion withholds the prerelease channel,
   so the switcher disappears with it and nothing in the UI advertises a version
   that is no longer published (its retired URLs redirect instead).
-- The sidebar treats each channel as a **topic of its own**: `ZodSharp 2.4.2` and
-  `ZodSharp 3.0.0-prerelease.2` are separate entries in the topic picker, each
-  with a flat page list, exactly as two projects would be. A channel is a whole
-  documentation set, not a section of one, so grouping both under a single
-  project topic would claim one tree while the pages belong to two. A
-  single-channel project keeps the bare project name.
+- The sidebar keeps **one entry per project**. Each channel contributes its own
+  topic internally, so the page list always matches the version being read, but
+  every topic for a project carries the project's name and the topic picker
+  collapses the duplicates. A version is chosen with the page switcher and never
+  appears in the sidebar; the switcher exists only while two versions are
+  published.
 - Every published version has its own machine-readable bundle. The default
   channel keeps `/projects/<id>/llms.txt` and `llms-full.txt`; any other channel
   mirrors its documentation URL shape at
diff --git a/src/src/components/starlight/TopicSelect.astro b/src/src/components/starlight/TopicSelect.astro
index 6d2e463..86f9e84 100644
--- a/src/src/components/starlight/TopicSelect.astro
+++ b/src/src/components/starlight/TopicSelect.astro
@@ -4,13 +4,27 @@ const { topics, isPageWithTopic } = Astro.locals.starlightSidebarTopics;
 if (!isPageWithTopic) {
   return null;
 }
+
+// A project that publishes more than one documentation version contributes one
+// topic per version, each with the page list for that version — but the versions
+// belong in the page switcher, not in the topic list. Collapse topics that share
+// a label, preferring the one the reader is currently on so its link stays
+// correct. `Map` preserves insertion order, so the catalogue order is unchanged.
+const byLabel = new Map<string, (typeof topics)[number]>();
+for (const topic of topics) {
+  const existing = byLabel.get(topic.label);
+  if (!existing || (topic.isCurrent && !existing.isCurrent)) {
+    byLabel.set(topic.label, topic);
+  }
+}
+const projectTopics = [...byLabel.values()];
 ---
 
 <label class="topic-select">
   <span class="sr-only">Select documentation</span>
   <select onchange="window.location.assign(this.value)">
     {
-      topics.map((topic) => (
+      projectTopics.map((topic) => (
         <option value={topic.link} selected={topic.isCurrent}>
           {topic.label}
         </option>
diff --git a/src/src/lib/docs/channels.ts b/src/src/lib/docs/channels.ts
index 423ecd0..bf14a7d 100644
--- a/src/src/lib/docs/channels.ts
+++ b/src/src/lib/docs/channels.ts
@@ -433,13 +433,13 @@ export function channelDisplayLabel(channel: { id: DocChannelId; label: string }
 }
 
 /**
- * Sidebar topic label for one documentation version.
+ * Version-qualified label for one documentation version.
  *
- * Each channel is a first-class documentation set (ADR 0009), so a project that
- * publishes two channels appears as two topics — `ZodSharp 2.4.2` and
- * `ZodSharp 3.0.0-prerelease.2` — rather than as one topic that groups both
- * versions. The product name stays in front so the pair still reads as the same
- * product, and a single-channel project keeps its historical bare name.
+ * Used where two versions are listed as siblings — the documentation portal and
+ * the root `llms.txt` link list — so `ZodSharp 2.4.2` and
+ * `ZodSharp 3.0.0-prerelease.2` are distinguishable. The sidebar does **not**
+ * use it: there a project appears once, and the page switcher chooses the
+ * version. A single-channel project keeps the bare project name.
  */
 export function channelTopicLabel(
   projectName: string,
diff --git a/src/src/lib/docs/sidebar.ts b/src/src/lib/docs/sidebar.ts
index cbc4042..159a0b7 100644
--- a/src/src/lib/docs/sidebar.ts
+++ b/src/src/lib/docs/sidebar.ts
@@ -1,7 +1,7 @@
 import type { ResolvedProject } from '../manifest/load';
 import type { DocsManifest, DocsManifestChannel } from './aggregate';
 
-import { channelBasePath, channelTopicLabel } from './channels';
+import { channelBasePath } from './channels';
 
 export interface SidebarSlugEntry {
   label?: string;
@@ -53,14 +53,12 @@ export function buildChannelItems(
 /**
  * Build the sidebar topics for a single project's documentation.
  *
- * A channel is a whole documentation set, not a section of one: the same
- * product at a different version has different pages, different links and its
- * own `llms.txt`. Grouping the channels inside one topic would make the sidebar
- * claim a single tree while the pages belong to two, and it would bury the
- * second version behind a collapsed group. Each channel therefore becomes its
- * own topic — `ZodSharp 2.4.2` and `ZodSharp 3.0.0-prerelease.2` — with a flat
- * item list, so switching versions works exactly like switching projects.
- * A single-channel project keeps its historical topic (the bare project name).
+ * A channel is a whole documentation set, so each published version contributes
+ * its own topic and its own page list — the sidebar must describe the version
+ * the reader is on. The versions are **not** shown in the sidebar, though: every
+ * topic for a project carries the project's name, and the topic picker collapses
+ * the duplicates (see `TopicSelect.astro`). Choosing a version is the job of the
+ * page switcher, which only appears while two versions are published.
  */
 export function buildProjectTopics(
   project: ResolvedProject,
@@ -78,7 +76,7 @@ export function buildProjectTopics(
   return ordered
     .map((channel) => ({
       id: channels.length > 1 ? `${project.id}-${channel.id}` : project.id,
-      label: channelTopicLabel(project.name, channel, channels.length),
+      label: project.name,
       link: channelBasePath(project.id, channel.id, channel.default),
       items: buildChannelItems(project.id, channel),
     }))
diff --git a/src/src/pages/docs/index.astro b/src/src/pages/docs/index.astro
index 178b088..f24697a 100644
--- a/src/src/pages/docs/index.astro
+++ b/src/src/pages/docs/index.astro
@@ -82,9 +82,8 @@ const pageCount = docsManifest?.projects.reduce(
           <h2 class="text-xl font-semibold">Documentation versions</h2>
           <p class="mt-3 max-w-3xl text-sm text-muted">
             Some projects publish more than one version of their documentation. Each version is a
-            documentation set in its own right — its own pages, its own sidebar entry and its own
-            machine-readable bundle — because installing a different version means reading different
-            docs.
+            documentation set in its own right — its own pages and its own machine-readable bundle —
+            because installing a different version means reading different docs.
           </p>
           <ul class="mt-5 space-y-5">
             {versionedProjects.map(({ project, channels }) => (
diff --git a/src/tests/dist/built-output.test.ts b/src/tests/dist/built-output.test.ts
index 15cf035..b146962 100644
--- a/src/tests/dist/built-output.test.ts
+++ b/src/tests/dist/built-output.test.ts
@@ -447,15 +447,27 @@ describe('built documentation channels', () => {
     }
   });
 
-  test.skipIf(!prerelease)('each documentation version is its own sidebar topic', () => {
-    // Versions are distinct sidebar entries, not groups inside one project
-    // topic: the same product, two documentation sets. The topic picker lists
-    // both, each pointing at its own landing page.
+  test.skipIf(!prerelease)('the sidebar lists the project once and hides the versions', () => {
+    // The reader is on the prerelease version: its page list is the sidebar
+    // body, but the topic picker still lists `ZodSharp` exactly once and no
+    // version label appears in any option.
     const content = requireBuilt(prereleaseIndex);
-    expect(content).toContain(`ZodSharp ${live!.label}`);
-    expect(content).toContain(`ZodSharp ${prerelease!.label}`);
-    expect(content).toContain('value="/docs/zodsharp/"');
-    expect(content).toContain('value="/docs/zodsharp/prerelease/"');
+    const optionLabels = [...content.matchAll(/<option[^>]*>([^<]*)<\/option>/g)].map((match) =>
+      (match[1] ?? '').trim(),
+    );
+    expect(optionLabels).toContain('ZodSharp');
+    expect(optionLabels.some((label) => label.includes(live!.label))).toBe(false);
+    expect(optionLabels.some((label) => label.includes(prerelease!.label))).toBe(false);
+    expect((content.match(/value="\/docs\/zodsharp/g) ?? []).length).toBe(1);
+
+    // The page switcher is the only place versions appear, and it shows both.
+    expect(content).toContain(channelDisplayLabel(live!));
+    expect(content).toContain(channelDisplayLabel(prerelease!));
+  });
+
+  test('the version switcher only appears while a second version is published', () => {
+    // A single-channel project has no version to choose.
+    expect(requireBuilt('docs/results/index.html')).not.toContain('doc-channel-menu');
   });
 
   test.skipIf(!prerelease)('each documentation version publishes its own llms bundles', () => {
diff --git a/src/tests/unit/docs-sidebar.test.ts b/src/tests/unit/docs-sidebar.test.ts
index 70a0334..644ebeb 100644
--- a/src/tests/unit/docs-sidebar.test.ts
+++ b/src/tests/unit/docs-sidebar.test.ts
@@ -66,12 +66,12 @@ describe('documentation sidebar topics', () => {
     ]);
   });
 
-  test('each published version is its own topic, not a group inside one', () => {
+  test('a versioned project still reads as one project in the sidebar', () => {
     const topics = buildProjectTopics(project!, bothChannels());
-    expect(topics.map((topic) => topic.label)).toEqual([
-      'ZodSharp 2.4.2',
-      'ZodSharp 3.0.0-prerelease.2',
-    ]);
+    // One topic per version internally (each with that version's pages), but
+    // every topic carries the project name: versions never leak into the
+    // sidebar — the page switcher is where a reader chooses one.
+    expect(topics.map((topic) => topic.label)).toEqual(['ZodSharp', 'ZodSharp']);
     expect(topics.map((topic) => topic.link)).toEqual([
       '/docs/zodsharp/',
       '/docs/zodsharp/prerelease/',
@@ -79,6 +79,13 @@ describe('documentation sidebar topics', () => {
     expect(topics.map((topic) => topic.id)).toEqual(['zodsharp-live', 'zodsharp-prerelease']);
   });
 
+  test('the sidebar never names a version', () => {
+    for (const topic of buildProjectTopics(project!, bothChannels())) {
+      expect(topic.label).not.toContain('2.4.2');
+      expect(topic.label).not.toContain('3.0.0');
+    }
+  });
+
   test('the two versions never share a page or a group', () => {
     const [live, prerelease] = buildProjectTopics(project!, bothChannels());
     const liveSlugs = new Set(live!.items.map((item) => item.slug));