From e908b9b4de48aa0ca88f2b3f18717211536cd94a Mon Sep 17 00:00:00 2001
From: Pawel Kosiec <pawel.kosiec@databricks.com>
Date: Tue, 3 Feb 2026 15:07:26 +0100
Subject: [PATCH] docs: fix autogeneration of the `appkit-ui` API reference
 sidebar

---
 docs/docs/api/appkit-ui/data/_category_.json |  4 +++
 docs/docs/api/appkit-ui/ui/_category_.json   |  4 +++
 docs/docusaurus.config.ts                    | 26 ++++++++++++-----
 docs/sidebars.ts                             | 20 ++-----------
 tools/generate-component-mdx.ts              | 30 +++++++++++++++++++-
 5 files changed, 58 insertions(+), 26 deletions(-)
 create mode 100644 docs/docs/api/appkit-ui/data/_category_.json
 create mode 100644 docs/docs/api/appkit-ui/ui/_category_.json

diff --git a/docs/docs/api/appkit-ui/data/_category_.json b/docs/docs/api/appkit-ui/data/_category_.json
new file mode 100644
index 00000000..693fb366
--- /dev/null
+++ b/docs/docs/api/appkit-ui/data/_category_.json
@@ -0,0 +1,4 @@
+{
+  "label": "Data components",
+  "position": 3
+}
diff --git a/docs/docs/api/appkit-ui/ui/_category_.json b/docs/docs/api/appkit-ui/ui/_category_.json
new file mode 100644
index 00000000..32abf7e0
--- /dev/null
+++ b/docs/docs/api/appkit-ui/ui/_category_.json
@@ -0,0 +1,4 @@
+{
+  "label": "UI components",
+  "position": 2
+}
diff --git a/docs/docusaurus.config.ts b/docs/docusaurus.config.ts
index db8953e6..b67c025a 100644
--- a/docs/docusaurus.config.ts
+++ b/docs/docusaurus.config.ts
@@ -85,13 +85,25 @@ const config: Config = {
             ...args
           }) {
             const sidebarItems = await defaultSidebarItemsGenerator(args);
-            // exclude API reference - this category is handled manually in sidebars.ts
-            return sidebarItems.filter(
-              (item) =>
-                item.type !== "category" ||
-                item.link?.type !== "doc" ||
-                item.link.id !== "api/index",
-            );
+
+            return sidebarItems.filter((item) => {
+              // Exclude API reference category - handled manually in sidebars.ts
+              if (
+                item.type === "category" &&
+                item.link?.type === "doc" &&
+                item.link.id === "api/index"
+              ) {
+                return false;
+              }
+
+              // Exclude api/appkit-ui/index - automatically used as category link in sidebars.ts
+              // Explicit dirName in sidebars.ts bypasses automatic exclusion
+              if (item.type === "doc" && item.id === "api/appkit-ui/index") {
+                return false;
+              }
+
+              return true;
+            });
           },
         },
         theme: {
diff --git a/docs/sidebars.ts b/docs/sidebars.ts
index c12d4dab..f7d99e0f 100644
--- a/docs/sidebars.ts
+++ b/docs/sidebars.ts
@@ -83,24 +83,8 @@ const sidebars: SidebarsConfig = {
           },
           items: [
             {
-              type: "category",
-              label: "UI components",
-              items: [
-                {
-                  type: "autogenerated",
-                  dirName: "api/appkit-ui/ui",
-                },
-              ],
-            },
-            {
-              type: "category",
-              label: "Data components",
-              items: [
-                {
-                  type: "autogenerated",
-                  dirName: "api/appkit-ui/data",
-                },
-              ],
+              type: "autogenerated",
+              dirName: "api/appkit-ui",
             },
           ],
         },
diff --git a/tools/generate-component-mdx.ts b/tools/generate-component-mdx.ts
index 1f11bac7..3bc0bec2 100644
--- a/tools/generate-component-mdx.ts
+++ b/tools/generate-component-mdx.ts
@@ -23,6 +23,7 @@ const FILE_EXTENSIONS = {
   EXAMPLE: ".example.tsx",
   TEST_PATTERN: ".test.",
   INDEX: "/index.tsx",
+  CATEGORY_CONFIG: "_category_.json",
 } as const;
 
 const COMPONENT_PATTERNS = {
@@ -557,7 +558,8 @@ function main() {
   // Create output directory if it doesn't exist
   fs.mkdirSync(outputDir, { recursive: true });
 
-  // Delete only subdirectories (preserve files like index.md)
+  // Delete only subdirectories (preserve root-level files)
+  // This preserves files like _index.md (category link) and styling.md (manual docs)
   if (fs.existsSync(outputDir)) {
     const entries = fs.readdirSync(outputDir, { withFileTypes: true });
     for (const entry of entries) {
@@ -576,6 +578,32 @@ function main() {
   fs.mkdirSync(dataOutputDir, { recursive: true });
   fs.mkdirSync(uiOutputDir, { recursive: true });
 
+  // Create _category_.json files for proper sidebar labels
+  fs.writeFileSync(
+    path.join(uiOutputDir, FILE_EXTENSIONS.CATEGORY_CONFIG),
+    `${JSON.stringify(
+      {
+        label: "UI components",
+        position: 2,
+      },
+      null,
+      2,
+    )}\n`,
+    MARKDOWN.FILE_ENCODING,
+  );
+  fs.writeFileSync(
+    path.join(dataOutputDir, FILE_EXTENSIONS.CATEGORY_CONFIG),
+    `${JSON.stringify(
+      {
+        label: "Data components",
+        position: 3,
+      },
+      null,
+      2,
+    )}\n`,
+    MARKDOWN.FILE_ENCODING,
+  );
+
   let count = 0;
 
   const fileNameCounts = new Map<string, number>();