Big sidebar refactor (#110)

Author: rambleraptor

astro.config.mjs

@@ -3,15 +3,125 @@ import starlight from "@astrojs/starlight";
 import * as fs from "fs";
 import rehypeMermaid from "rehype-mermaid";
 import starlightBlog from "starlight-blog";
-import starlightSidebarTopics from "starlight-sidebar-topics";
 import tailwindcss from "@tailwindcss/vite";
 
 // Helper function to check if an edition is the latest
 const isLatestEdition = (edition) => edition.folder === ".";
 
-let sidebar = JSON.parse(
-  fs.readFileSync("generated/sidebar-from-site-structure.json"),
+// Load site structure and transform it into Starlight sidebar format
+const siteStructure = JSON.parse(
+  fs.readFileSync("generated/site-structure.json", "utf-8"),
 );
+
+// Helper function to get the latest edition from site structure
+function getLatestEditionName(siteStructure) {
+  const editionNames = Object.keys(siteStructure.aeps.editions);
+  if (editionNames.length === 0) return null;
+
+  // Check for edition with folder = "." (latest edition)
+  const currentFolderEdition = editionNames.find(
+    (name) => siteStructure.aeps.editions[name].folder === ".",
+  );
+  if (currentFolderEdition) return currentFolderEdition;
+
+  // Check for standard names
+  const standardEdition = editionNames.find((name) =>
+    ["general", "main", "default"].includes(name.toLowerCase()),
+  );
+  if (standardEdition) return standardEdition;
+
+  // Fall back to first edition
+  return editionNames[0];
+}
+
+// Transform site structure into Starlight sidebar format
+function transformSiteStructureToSidebar(siteStructure) {
+  const sidebar = [];
+
+  // Overview section
+  sidebar.push({
+    label: siteStructure.overview.metadata.label,
+    items: siteStructure.overview.pages.map((page) => page.link),
+  });
+
+  // AEPs section
+  const latestEditionName = getLatestEditionName(siteStructure);
+  const aepItems = [];
+  if (latestEditionName) {
+    const latestEdition = siteStructure.aeps.editions[latestEditionName];
+    for (const category of latestEdition.categories) {
+      aepItems.push({
+        label: category.title,
+        items: category.aeps.map((aep) => ({
+          label: `${aep.id}. ${aep.title}`,
+          link: aep.id.toString(),
+        })),
+      });
+    }
+  }
+  sidebar.push({
+    label: siteStructure.aeps.metadata.label,
+    items: aepItems,
+  });
+
+  // Tooling section
+  const toolingItems = [];
+  for (const page of siteStructure.tooling.pages) {
+    toolingItems.push({
+      label: page.label,
+      link: page.link,
+    });
+  }
+
+  // Add Protobuf Linter section
+  if (siteStructure.tooling.linterRules?.length > 0) {
+    toolingItems.push({
+      label: "Protobuf Linter",
+      items: [
+        "tooling/linter",
+        {
+          label: "Rules",
+          collapsed: true,
+          items: siteStructure.tooling.linterRules.map(
+            (rule) => `tooling/linter/rules/${rule}`,
+          ),
+        },
+      ],
+    });
+  }
+
+  // Add OpenAPI Linter section
+  if (siteStructure.tooling.openAPILinterRules?.length > 0) {
+    toolingItems.push({
+      label: "OpenAPI Linter",
+      items: [
+        "tooling/openapi-linter",
+        {
+          label: "Rules",
+          collapsed: true,
+          items: siteStructure.tooling.openAPILinterRules
+            .sort((a, b) => a.localeCompare(b))
+            .map((rule) => `tooling/openapi-linter/rules/${rule}`),
+        },
+      ],
+    });
+  }
+
+  sidebar.push({
+    label: siteStructure.tooling.metadata.label,
+    items: toolingItems,
+  });
+
+  // Blog section - content is populated by starlight-blog plugin middleware
+  sidebar.push({
+    label: siteStructure.blog.metadata.label,
+    items: [],
+  });
+
+  return sidebar;
+}
+
+let sidebar = transformSiteStructureToSidebar(siteStructure);
 let redirects = JSON.parse(fs.readFileSync("generated/redirects.json"));
 let config = JSON.parse(fs.readFileSync("generated/config.json"));
 let aepEditions = JSON.parse(fs.readFileSync("aep-editions.json"));
@@ -32,29 +142,8 @@ export default defineConfig({
         // Path to your Tailwind base styles:
         "./src/styles/global.css",
       ],
-      plugins: [
-        starlightBlog({ navigation: "none" }),
-        starlightSidebarTopics(sidebar, {
-          topics: {
-            aeps: aepEditions.editions
-              .filter((edition) => !isLatestEdition(edition))
-              .flatMap((edition) => [
-                `/${edition.folder}`,
-                `/${edition.folder}/**/*`,
-              ]),
-          },
-          exclude: [
-            "/blog",
-            "/blog/**/*",
-            ...aepEditions.editions
-              .filter((edition) => !isLatestEdition(edition))
-              .flatMap((edition) => [
-                `/${edition.folder}`,
-                `/${edition.folder}/**/*`,
-              ]),
-          ],
-        }),
-      ],
+      sidebar: sidebar,
+      plugins: [starlightBlog({ navigation: "none" })],
       social: [
         { icon: "github", label: "GitHub", href: config.urls.repo },
         {
@@ -71,6 +160,7 @@ export default defineConfig({
       components: {
         Banner: "./src/components/overrides/Banner.astro",
         Head: "./src/components/overrides/Head.astro",
+        Sidebar: "./src/components/overrides/Sidebar.astro",
         SkipLink: "./src/components/overrides/SkipLink.astro",
         TableOfContents: "./src/components/overrides/TableOfContents.astro",
         ThemeSelect: "./src/components/overrides/ThemeSelect.astro",

package-lock.json

@@ -27,7 +27,6 @@
     "rehype-mermaid": "^3.0.0",
     "sharp": "^0.32.5",
     "starlight-blog": "^0.24.0",
-    "starlight-sidebar-topics": "^0.6.0",
     "tailwindcss": "^4.1.4",
     "vite-plugin-radar": "^0.9.6"
   },

package.json

@@ -34,7 +34,6 @@ import {
   writeSiteStructure,
   type SiteStructure,
 } from "../src/utils/site-structure";
-import { assembleSidebarFromSiteStructure } from "../src/utils/sidebar-from-site-structure";
 
 const AEP_LOC = process.env.AEP_LOCATION || "";
 const AEP_LINTER_LOC = process.env.AEP_LINTER_LOC || "";
@@ -143,14 +142,16 @@ async function writePage(
   filename: string,
   outputPath: string,
   title?: string,
-) {
+): Promise<string> {
   const filePath = path.join(dirPath, filename);
   logFileRead(filePath, "Page content");
   let contents = new Markdown(fs.readFileSync(filePath, "utf-8"), {});
+  const pageTitle = title ?? getTitle(contents.contents);
   contents.frontmatter = {
-    title: title ?? getTitle(contents.contents),
+    title: pageTitle,
   };
   writeFile(outputPath, contents.removeTitle().build());
+  return pageTitle;
 }
 
 async function writePagesToSiteStructure(
@@ -167,21 +168,21 @@ async function writePagesToSiteStructure(
   );
 
   for (var file of files) {
-    writePage(
+    const title = await writePage(
       path.join(dirPath, "pages/general"),
       file.name,
       path.join("src/content/docs", file.name),
     );
     const link = file.name.replace(".md", "");
-    addOverviewPage(siteStructure, { label: link, link });
+    addOverviewPage(siteStructure, { label: title, link });
   }
-  writePage(
+  const contributingTitle = await writePage(
     dirPath,
     "CONTRIBUTING.md",
     path.join("src/content/docs", "contributing.md"),
   );
   addOverviewPage(siteStructure, {
-    label: "contributing",
+    label: contributingTitle,
     link: "contributing",
   });
   return siteStructure;
@@ -489,7 +490,3 @@ if (AEP_EDITION_2026 != "") {
 
 // Write site structure to JSON
 writeSiteStructure(siteStructure, "generated/site-structure.json");
-
-// Assemble sidebar from site structure and write it
-const sidebar = assembleSidebarFromSiteStructure(siteStructure);
-writeSidebar(sidebar, "sidebar-from-site-structure.json");