Generate API sidebar dynamically from schema with version-aware links (#89)

Author: kylemclaren

.gitignore

@@ -63,3 +63,5 @@ cli-test-report.json
 src/content/docs/api/*
 !src/content/docs/api/_manual/
 .playwright-mcp/
+# Auto-generated
+src/lib/api-sidebar.ts

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}>

src/lib/api-versions.ts

@@ -94,3 +94,70 @@ export function buildVersionedPath(versionId: string, page: string): string {
   const basePath = `/api/${slug}`;
   return page ? `${basePath}/${page}` : basePath;
 }
+
+/**
+ * Rewrite an API URL to use a different version.
+ * Preserves the page path and hash fragment.
+ * e.g., ("/api/v001-rc30/exec#execute", "dev-latest") → "/api/dev-latest/exec#execute"
+ */
+export function rewriteApiUrl(url: string, targetVersionId: string): string {
+  // Match /api/{version}/{page}#{hash} or /api/{version}/{page} or /api/{version}/
+  const match = url.match(/^\/api\/[^/]+\/?(.*)$/);
+  if (!match) return url;
+
+  const pageAndHash = match[1]; // e.g., "exec#execute-command" or "exec" or ""
+  const targetSlug = versionToSlug(targetVersionId);
+
+  if (!pageAndHash) {
+    return `/api/${targetSlug}/`;
+  }
+  return `/api/${targetSlug}/${pageAndHash}`;
+}
+
+// Re-export types for sidebar transformation (used by Sidebar.astro)
+export interface SidebarLink {
+  type: 'link';
+  label: string;
+  href: string;
+  isCurrent: boolean;
+  badge?: { text: string; variant: string };
+  attrs?: Record<string, string>;
+}
+
+export interface SidebarGroup {
+  type: 'group';
+  label: string;
+  entries: SidebarEntry[];
+  collapsed: boolean;
+  badge?: { text: string; variant: string };
+}
+
+export type SidebarEntry = SidebarLink | SidebarGroup;
+
+/**
+ * Recursively transform sidebar entries to use a specific API version.
+ * Only affects links that start with /api/.
+ */
+export function transformSidebarForVersion(
+  entries: SidebarEntry[],
+  targetVersionId: string,
+): SidebarEntry[] {
+  return entries.map((entry): SidebarEntry => {
+    if (entry.type === 'link') {
+      // Only transform API links
+      if (entry.href.startsWith('/api/')) {
+        return {
+          ...entry,
+          href: rewriteApiUrl(entry.href, targetVersionId),
+        };
+      }
+      return entry;
+    }
+
+    // It's a group - recurse into entries
+    return {
+      ...entry,
+      entries: transformSidebarForVersion(entry.entries, targetVersionId),
+    };
+  });
+}