diff --git a/docusaurus.config.ts b/docusaurus.config.ts index 5c7b0a0..cfef3ea 100644 --- a/docusaurus.config.ts +++ b/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 diff --git a/server/sidebar-order.test.ts b/server/sidebar-order.test.ts index 9e461f6..e653650 100644 --- a/server/sidebar-order.test.ts +++ b/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; @@ -503,3 +503,71 @@ describe.only("orderSidebarItems", () => { expect(actual).toEqual(c.expected); }); }); + +describe("removeRedundantItems", () => { + interface testCase { + description: string; + input: Array; + dirname: string; + expected: Array; + } + + // 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 = [ + { + 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); + }); +}); diff --git a/server/sidebar-order.ts b/server/sidebar-order.ts index 5896e76..f8aa0b6 100644 --- a/server/sidebar-order.ts +++ b/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, + dirname: string +): Array => { + // 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 + ); + }); +};