Make sidebar loading resilient for builds

Author: ziodave

README.md

@@ -32,6 +32,14 @@ $ npm run typecheck
 
 This runs TypeScript checks using the project `tsconfig.json` (which extends the Docusaurus base config).
 
+### Sidebar Checks
+
+```
+$ npm run test:sidebars
+```
+
+This verifies that API sidebar modules can be loaded from either `.js` or `.ts` files.
+
 ### Deployment
 
 Using SSH:

TODO.md

@@ -2,3 +2,5 @@
 
 - [x] 2026-02-05 Bump docs version to 3.12.0 and refresh the Version Notice with the Monitor API guide.
 - [x] 2026-02-05 Fix typecheck by aligning tsconfig/types and sidebar imports.
+- [x] 2026-02-05 Make sidebar loading resilient to .js/.ts generation differences and add a test.
+- [x] 2026-02-05 Bump patch version to 3.12.1 for sidebar build fix.

package.json

@@ -1,6 +1,6 @@
 {
   "name": "docs",
-  "version": "3.12.0",
+  "version": "3.12.1",
   "private": true,
   "scripts": {
     "docusaurus": "docusaurus",
@@ -10,6 +10,7 @@
     "deploy": "docusaurus deploy",
     "clear": "docusaurus clear",
     "serve": "docusaurus serve",
+    "test:sidebars": "node scripts/sidebars-utils.test.js",
     "write-translations": "docusaurus write-translations",
     "write-heading-ids": "docusaurus write-heading-ids",
     "typecheck": "tsc"

scripts/sidebars-utils.js

@@ -0,0 +1,27 @@
+const fs = require("fs");
+const path = require("path");
+
+function loadSidebar(relativePathBase) {
+  const jsPath = `${relativePathBase}.js`;
+  const tsPath = `${relativePathBase}.ts`;
+  const absJsPath = path.resolve(__dirname, "..", jsPath);
+  const absTsPath = path.resolve(__dirname, "..", tsPath);
+
+  if (fs.existsSync(absJsPath)) {
+    const mod = require(absJsPath);
+    return mod.default ?? mod;
+  }
+
+  if (fs.existsSync(absTsPath)) {
+    const mod = require(absTsPath);
+    return mod.default ?? mod;
+  }
+
+  throw new Error(
+    `Sidebar module not found. Tried ${absJsPath} and ${absTsPath}.`
+  );
+}
+
+module.exports = {
+  loadSidebar,
+};

scripts/sidebars-utils.test.js

@@ -0,0 +1,32 @@
+const assert = require("assert");
+const { loadSidebar } = require("./sidebars-utils");
+
+const sidebarPaths = [
+  "./docs/api/agent/sidebar",
+  "./docs/api/analysis/sidebar",
+  "./docs/api/audit/sidebar",
+  "./docs/api/classification/sidebar",
+  "./docs/api/content-evaluations/sidebar",
+  "./docs/api/content-generation/sidebar",
+  "./docs/api/events/sidebar",
+  "./docs/api/fact-check/sidebar",
+  "./docs/api/graphql/sidebar",
+  "./docs/api/gsc-url-inspections/sidebar",
+  "./docs/api/inspector/sidebar",
+  "./docs/api/long-tail/sidebar",
+  "./docs/api/manager/sidebar",
+  "./docs/api/middleware/sidebar",
+  "./docs/api/query-fan-out/sidebar",
+  "./docs/api/sitemap-generator/sidebar",
+  "./docs/api/summarizer/sidebar",
+];
+
+for (const sidebarPath of sidebarPaths) {
+  const loaded = loadSidebar(sidebarPath);
+  assert.ok(
+    Array.isArray(loaded),
+    `Expected ${sidebarPath} to resolve to an array.`
+  );
+}
+
+console.log("sidebars-utils.test.js: all sidebar modules resolved.");

sidebars.js

@@ -1,5 +1,7 @@
 // @ts-check
 
+const { loadSidebar } = require("./scripts/sidebars-utils");
+
 /** @type {import('@docusaurus/plugin-content-docs').SidebarsConfig} */
 const sidebars = {
   docs: [
@@ -241,87 +243,87 @@ const sidebars = {
         {
           type: "category",
           label: "Agent WordLift",
-          items: require("./docs/api/agent/sidebar.js").default,
+          items: loadSidebar("./docs/api/agent/sidebar"),
         },
         {
           type: "category",
           label: "Audit",
-          items: require("./docs/api/audit/sidebar.js").default,
+          items: loadSidebar("./docs/api/audit/sidebar"),
         },
         {
           type: "category",
           label: "Analysis",
-          items: require("./docs/api/analysis/sidebar.js").default,
+          items: loadSidebar("./docs/api/analysis/sidebar"),
         },
         {
           type: "category",
           label: "Classification",
-          items: require("./docs/api/classification/sidebar.js").default,
+          items: loadSidebar("./docs/api/classification/sidebar"),
         },
         {
           type: "category",
           label: "Content Generation",
-          items: require("./docs/api/content-generation/sidebar.js").default,
+          items: loadSidebar("./docs/api/content-generation/sidebar"),
         },
         {
           type: "category",
           label: "Content Evaluations",
-          items: require("./docs/api/content-evaluations/sidebar.js").default,
+          items: loadSidebar("./docs/api/content-evaluations/sidebar"),
         },
         {
           type: "category",
           label: "Fact Check",
-          items: require("./docs/api/fact-check/sidebar.js").default,
+          items: loadSidebar("./docs/api/fact-check/sidebar"),
         },
         {
           type: "category",
           label: "GraphQL",
-          items: require("./docs/api/graphql/sidebar.js").default,
+          items: loadSidebar("./docs/api/graphql/sidebar"),
         },
         {
           type: "category",
           label: "Inspector",
-          items: require("./docs/api/inspector/sidebar.js").default,
+          items: loadSidebar("./docs/api/inspector/sidebar"),
         },
         {
           type: "category",
           label: "KPI Events",
-          items: require("./docs/api/events/sidebar.js").default,
+          items: loadSidebar("./docs/api/events/sidebar"),
         },
         {
           type: "category",
           label: "Long Tail",
-          items: require("./docs/api/long-tail/sidebar.js").default,
+          items: loadSidebar("./docs/api/long-tail/sidebar"),
         },
         {
           type: "category",
           label: "Manager",
-          items: require("./docs/api/manager/sidebar.js").default,
+          items: loadSidebar("./docs/api/manager/sidebar"),
         },
         {
           type: "category",
           label: "Google Search Console",
-          items: require("./docs/api/gsc-url-inspections/sidebar.js").default,
+          items: loadSidebar("./docs/api/gsc-url-inspections/sidebar"),
         },
         {
           type: "category",
           label: "Middleware",
-          items: require("./docs/api/middleware/sidebar.js").default,
+          items: loadSidebar("./docs/api/middleware/sidebar"),
         },
         {
           type: "category",
           label: "Summarization",
-          items: require("./docs/api/summarizer/sidebar.js").default,
+          items: loadSidebar("./docs/api/summarizer/sidebar"),
         },
         {
           type: "category",
           label: "Sitemap Generator",
-          items: require("./docs/api/sitemap-generator/sidebar.js").default,
+          items: loadSidebar("./docs/api/sitemap-generator/sidebar"),
         },
         {
           type: "category",
           label: "Query Fan-Out",
-          items: require("./docs/api/query-fan-out/sidebar.js").default,
+          items: loadSidebar("./docs/api/query-fan-out/sidebar"),
         },
       ],
     },