docs: fix autogeneration of the appkit-ui API reference sidebar (#80)

Author: pkosiec

docs/docs/api/appkit-ui/data/_category_.json

@@ -0,0 +1,4 @@
+{
+  "label": "Data components",
+  "position": 3
+}

docs/docs/api/appkit-ui/ui/_category_.json

@@ -0,0 +1,4 @@
+{
+  "label": "UI components",
+  "position": 2
+}

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: {

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",
             },
           ],
         },

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>();