Remove redundant sidebar items

docusaurus.config.ts

@@ -23,7 +23,10 @@ import {
   getRootDir,
   updatePathsInIncludes,
 } from "./server/asset-path-helpers";
-import { orderSidebarItems } from "./server/sidebar-order";
+import {
+  orderSidebarItems,
+  removeRedundantItems,
+} from "./server/sidebar-order";
 import { extendedPostcssConfigPlugin } from "./server/postcss";
 import { rehypeHLJS } from "./server/rehype-hljs";
 import { definer as hcl } from "highlightjs-terraform";
@@ -186,14 +189,20 @@ const config: Config = {
             categoriesMetadata,
             isCategoryIndex,
           });
+
           const idToDocPage = new Map();
           docs.forEach((d) => {
             idToDocPage.set(d.id, d);
           });
+
           const getDocPageByID = (id: string) => {
             return idToDocPage.get(id);
           };
-          return orderSidebarItems(items, getDocPageByID);
+
+          return orderSidebarItems(
+            removeRedundantItems(items, item.dirName),
+            getDocPageByID
+          );
         },
         // Host docs on the root page, later it will be exposed on goteleport.com/docs
         // next to the website and blog

server/sidebar-order.test.ts

@@ -1,6 +1,6 @@
 import { describe, expect, test } from "@jest/globals";
 import { basename, dirname } from "node:path";
-import { orderSidebarItems } from "./sidebar-order";
+import { orderSidebarItems, removeRedundantItems } from "./sidebar-order";
 import type { docPage } from "./sidebar-order";
 import type { NormalizedSidebarItem } from "@docusaurus/plugin-content-docs/src/sidebars/types.ts";
 
@@ -24,7 +24,7 @@ function getDocPageForId(id: string): docPage {
   };
 }
 
-describe.only("orderSidebarItems", () => {
+describe("orderSidebarItems", () => {
   interface testCase {
     description: string;
     input: Array<NormalizedSidebarItem>;
@@ -503,3 +503,71 @@ describe.only("orderSidebarItems", () => {
     expect(actual).toEqual(c.expected);
   });
 });
+
+describe("removeRedundantItems", () => {
+  interface testCase {
+    description: string;
+    input: Array<NormalizedSidebarItem>;
+    dirname: string;
+    expected: Array<NormalizedSidebarItem>;
+  }
+
+  // To write a test case, you can print the items array returned by
+  // defaultSidebarItemsGenerator in docusaurus.config.ts and find the
+  // subarray of items you would like to include.
+  const testCases: Array<testCase> = [
+    {
+      description: "Removes top-level category index pages",
+      dirname: "reference",
+      input: [
+        {
+          type: "doc",
+          id: "reference/reference",
+        },
+        {
+          type: "category",
+          label: "My Docs Category",
+          items: [
+            {
+              type: "doc",
+              id: "reference/my-category/page-c",
+            },
+            {
+              type: "doc",
+              id: "reference/my-category/page-a",
+            },
+            {
+              type: "doc",
+              id: "reference/my-category/page-b",
+            },
+          ],
+        },
+      ],
+      expected: [
+        {
+          type: "category",
+          label: "My Docs Category",
+          items: [
+            {
+              type: "doc",
+              id: "reference/my-category/page-c",
+            },
+            {
+              type: "doc",
+              id: "reference/my-category/page-a",
+            },
+            {
+              type: "doc",
+              id: "reference/my-category/page-b",
+            },
+          ],
+        },
+      ],
+    },
+  ];
+
+  test.each(testCases)("$description", (c) => {
+    const actual = removeRedundantItems(c.input, c.dirname);
+    expect(actual).toEqual(c.expected);
+  });
+});

server/sidebar-order.ts

@@ -103,3 +103,26 @@ export const orderSidebarItems = (
     }
   });
 };
+
+// removeRedundantItems removes top-level category index pages from the sidebar,
+// since we expect these to be defined as links within each top-level category.
+export const removeRedundantItems = (
+  items: Array<NormalizedSidebarItem>,
+  dirname: string
+): Array<NormalizedSidebarItem> => {
+  // Return all items except for the one with the ID of the index page to
+  // remove from the body of the sidebar section. We expect the top-level category index
+  // page to be in, and named after, the section's root directory, e.g.:
+  //
+  // - "reference/reference"
+  // - "admin-guides/admin-guides"
+  return items.filter((item) => {
+    if (!item.hasOwnProperty("id")) {
+      return true;
+    }
+    return (
+      (item as { id: string; [propName: string]: unknown }).id !==
+      dirname + "/" + dirname
+    );
+  });
+};