Generate API sidebar dynamically from schema with version-aware links

- Add sidebar transformation utilities to api-versions.ts:
  - rewriteApiUrl() rewrites API URLs to target version
  - transformSidebarForVersion() recursively transforms sidebar entries
  - Type definitions for SidebarEntry, SidebarLink, SidebarGroup

- Update Sidebar.astro to transform sidebar at render time:
  - Detects current API version from URL path
  - Rewrites all /api/ links to match current version
  - Sidebar links now match the version being viewed

- Modify generate-api-docs.ts to output src/lib/api-sidebar.ts:
  - New generateUnifiedSidebarFile() function
  - Uses versionToSlug() for Astro-compatible paths
  - Auto-generated from API schema at build time

- Update sidebar.ts to import generated config:
  - Remove 150+ lines of hardcoded API Reference section
  - Import apiSidebarConfig from generated file

Benefits:
- Sidebar auto-updates when API schema changes
- New endpoints appear automatically
- Version switching shows correct links for each version

Co-Authored-By: Claude Opus 4.5 <[email protected]>

Author: kylemclaren

scripts/generate-api-docs.ts

@@ -21,6 +21,7 @@ import {
   API_VERSIONS,
   type APIVersion,
   DEFAULT_VERSION,
+  versionToSlug,
 } from '../src/lib/api-versions';
 
 const OUTPUT_BASE_DIR = './src/content/docs/api';
@@ -1217,8 +1218,11 @@ function generateSidebarItems(
   endpointsByCategory: Record<string, APIEndpoint[]>,
   versionId: string,
 ): SidebarItem[] {
+  // Use slugified version for Astro routing (dots removed)
+  const versionSlug = versionToSlug(versionId);
+
   const items: SidebarItem[] = [
-    { label: 'Overview', slug: `api/${versionId}` },
+    { label: 'Overview', slug: `api/${versionSlug}` },
   ];
 
   // Add manual pages (Sprites) with nested endpoint items
@@ -1227,7 +1231,7 @@ function generateSidebarItems(
       // Create a group with nested endpoint items
       const endpointItems: SidebarLink[] = page.endpoints.map((ep) => ({
         label: ep.title,
-        link: `/api/${versionId}/${page.category}#${slugifyEndpoint(ep.title)}`,
+        link: `/api/${versionSlug}/${page.category}#${slugifyEndpoint(ep.title)}`,
         attrs: getMethodAttrs(ep.method),
       }));
       items.push({
@@ -1238,7 +1242,7 @@ function generateSidebarItems(
     } else {
       items.push({
         label: page.title,
-        slug: `api/${versionId}/${page.category}`,
+        slug: `api/${versionSlug}/${page.category}`,
       });
     }
   }
@@ -1249,7 +1253,7 @@ function generateSidebarItems(
     if (endpoints.length > 0) {
       const endpointItems: SidebarLink[] = endpoints.map((ep) => ({
         label: ep.name,
-        link: `/api/${versionId}/${category}#${slugifyEndpoint(ep.name)}`,
+        link: `/api/${versionSlug}/${category}#${slugifyEndpoint(ep.name)}`,
         attrs: getMethodAttrs(ep.method),
       }));
       items.push({
@@ -1260,12 +1264,12 @@ function generateSidebarItems(
     } else {
       items.push({
         label: getCategoryTitle(category),
-        slug: `api/${versionId}/${category}`,
+        slug: `api/${versionSlug}/${category}`,
       });
     }
   }
 
-  items.push({ label: 'Type Definitions', slug: `api/${versionId}/types` });
+  items.push({ label: 'Type Definitions', slug: `api/${versionSlug}/types` });
 
   return items;
 }
@@ -1334,6 +1338,48 @@ ${itemsStr}
 `;
 }
 
+/**
+ * Generate the unified API sidebar config file for use in sidebar.ts.
+ * This uses the DEFAULT_VERSION and is imported by the main sidebar config.
+ */
+function generateUnifiedSidebarFile(
+  categories: string[],
+  endpointsByCategory: Record<string, APIEndpoint[]>,
+  versionId: string,
+): string {
+  const items = generateSidebarItems(
+    categories,
+    endpointsByCategory,
+    versionId,
+  );
+
+  // Generate TypeScript with proper typing
+  const itemsStr = items
+    .map((item) => serializeSidebarItem(item, 1))
+    .join(',\n');
+
+  const versionSlug = versionToSlug(versionId);
+
+  return `/**
+ * Auto-generated API sidebar configuration.
+ * Generated by scripts/generate-api-docs.ts
+ * DO NOT EDIT MANUALLY - changes will be overwritten.
+ *
+ * This file uses the default API version (${versionId} → ${versionSlug}) for sidebar links.
+ * The Sidebar.astro component dynamically rewrites these links based on
+ * the current URL's version, so users see version-appropriate links.
+ */
+
+import type { StarlightUserConfig } from '@astrojs/starlight/types';
+
+type SidebarItem = NonNullable<StarlightUserConfig['sidebar']>[number];
+
+export const apiSidebarConfig: SidebarItem[] = [
+${itemsStr}
+];
+`;
+}
+
 // ============================================================================
 // Manual page handling - shared across all versions
 // ============================================================================
@@ -1482,6 +1528,8 @@ async function generateVersionDocs(version: APIVersion): Promise<{
 // Main
 // ============================================================================
 
+const API_SIDEBAR_OUTPUT_PATH = './src/lib/api-sidebar.ts';
+
 async function main() {
   console.log(
     '🚀 Generating API documentation (versioned, double-pane layout)...',
@@ -1507,9 +1555,20 @@ async function main() {
     await mkdir(OUTPUT_BASE_DIR, { recursive: true });
   }
 
+  // Store default version data for unified sidebar generation
+  let defaultVersionData: {
+    categories: string[];
+    endpointsByCategory: Record<string, APIEndpoint[]>;
+  } | null = null;
+
   // Generate docs for each version
   for (const version of API_VERSIONS) {
-    await generateVersionDocs(version);
+    const versionData = await generateVersionDocs(version);
+
+    // Save default version data for sidebar generation
+    if (version.id === DEFAULT_VERSION.id) {
+      defaultVersionData = versionData;
+    }
 
     // Copy shared manual pages to this version
     await copyManualPagesToVersion(version.id);
@@ -1520,6 +1579,18 @@ async function main() {
   const redirectContent = await generateRootRedirectPage(DEFAULT_VERSION);
   await writeFile(join(OUTPUT_BASE_DIR, 'index.mdx'), redirectContent);
 
+  // Generate unified API sidebar config
+  if (defaultVersionData) {
+    console.log('\n📝 Generating unified API sidebar config...');
+    const sidebarContent = generateUnifiedSidebarFile(
+      defaultVersionData.categories,
+      defaultVersionData.endpointsByCategory,
+      DEFAULT_VERSION.id,
+    );
+    await writeFile(API_SIDEBAR_OUTPUT_PATH, sidebarContent);
+    console.log(`  ✅ Generated ${API_SIDEBAR_OUTPUT_PATH}`);
+  }
+
   console.log('\n🎉 All versions generated successfully!');
   console.log(`   Default version: ${DEFAULT_VERSION.id}`);
 }

src/components/Sidebar.astro

@@ -1,13 +1,28 @@
 ---
 import StarlightSidebar from '@astrojs/starlight/components/Sidebar.astro';
 import { VersionSelector } from './react/api/VersionSelector';
-import { getVersionFromPath, API_VERSIONS } from '@/lib/api-versions';
+import {
+	getVersionFromPath,
+	API_VERSIONS,
+	transformSidebarForVersion,
+	type SidebarEntry,
+} from '@/lib/api-versions';
 
 const currentPath = Astro.url.pathname;
 
 // Check if this is a versioned API page (or any page where we want to show the selector)
 const versionId = getVersionFromPath(currentPath);
 const showVersionSelector = versionId !== null && API_VERSIONS.length > 1;
+
+// Transform sidebar links to use the current API version
+// This ensures sidebar links match the version the user is viewing
+if (versionId && Astro.locals.starlightRoute?.sidebar) {
+	const originalSidebar = Astro.locals.starlightRoute.sidebar as SidebarEntry[];
+	Astro.locals.starlightRoute.sidebar = transformSidebarForVersion(
+		originalSidebar,
+		versionId,
+	);
+}
 ---
 
 <StarlightSidebar {...Astro.props}>