docs: support multiple sidebars in a project (#11768)

* changed to new sidebar across projects except resources

* finalize multi sidebar support

* clean up

* remove redundant property

* small changes

* fixes

* generate

* fix error

* fix initial open

www/packages/build-scripts/src/utils/get-sidebar-item-link.ts

@@ -1,6 +1,6 @@
 import { getFrontMatter, findPageTitle } from "docs-utils"
-import { ItemsToAdd, sidebarAttachHrefCommonOptions } from "../index.js"
-import { InteractiveSidebarItem } from "types"
+import { ItemsToAdd, sidebarAttachCommonOptions } from "../index.js"
+import { Sidebar } from "types"
 
 export async function getSidebarItemLink({
   filePath,
@@ -16,7 +16,7 @@ export async function getSidebarItemLink({
     return
   }
 
-  const newItem = sidebarAttachHrefCommonOptions([
+  const newItem = sidebarAttachCommonOptions([
     {
       type: "link",
       path:
@@ -25,7 +25,7 @@ export async function getSidebarItemLink({
       title: frontmatter.sidebar_label || findPageTitle(filePath) || "",
       description: frontmatter.sidebar_description || "",
     },
-  ])[0] as InteractiveSidebarItem
+  ])[0] as Sidebar.InteractiveSidebarItem
 
   return {
     ...newItem,

www/packages/build-scripts/src/utils/number-sidebar-items.ts

@@ -1,15 +1,15 @@
-import { InteractiveSidebarItem, SidebarItem, SidebarItemCategory } from "types"
+import { Sidebar } from "types"
 
 export default function numberSidebarItems(
-  sidebarItems: SidebarItem[],
+  sidebarItems: Sidebar.SidebarItem[],
   numbering = [1]
-): SidebarItem[] {
+): Sidebar.SidebarItem[] {
   if (!numbering.length) {
     numbering.push(1)
   }
   const isTopItems = numbering.length === 1
-  const numberedItems: SidebarItem[] = []
-  let parentItem: InteractiveSidebarItem | undefined
+  const numberedItems: Sidebar.SidebarItem[] = []
+  let parentItem: Sidebar.InteractiveSidebarItem | undefined
   sidebarItems.forEach((item) => {
     if (item.type === "separator") {
       ;(parentItem?.children || numberedItems).push(item)
@@ -29,6 +29,7 @@ export default function numberSidebarItems(
       numberedItems.push(
         item.type === "category"
           ? {
+              initialOpen: false,
               ...item,
               title: item.chapterTitle,
             }
@@ -43,7 +44,7 @@ export default function numberSidebarItems(
 
       parentItem = numberedItems[
         numberedItems.length - 1
-      ] as SidebarItemCategory
+      ] as Sidebar.SidebarItemCategory
     }
 
     if (item.children) {

www/packages/build-scripts/src/utils/sidebar-attach-href-common-options.ts

@@ -1,13 +1,13 @@
-import { RawSidebarItem } from "types"
+import { Sidebar } from "types"
 
-const commonOptions: Partial<RawSidebarItem> = {
+const commonOptions: Partial<Sidebar.RawSidebarItem> = {
   loaded: true,
   isPathHref: true,
 }
 
-export function sidebarAttachHrefCommonOptions(
-  sidebar: RawSidebarItem[]
-): RawSidebarItem[] {
+export function sidebarAttachCommonOptions(
+  sidebar: Sidebar.RawSidebarItem[]
+): Sidebar.RawSidebarItem[] {
   return sidebar.map((item) => {
     if (item.type === "separator") {
       return item
@@ -16,7 +16,7 @@ export function sidebarAttachHrefCommonOptions(
     return {
       ...commonOptions,
       ...item,
-      children: sidebarAttachHrefCommonOptions(item.children || []),
+      children: sidebarAttachCommonOptions(item.children || []),
     }
   })
 }

www/packages/build-scripts/src/utils/sidebar-sorting.ts

@@ -1,14 +1,14 @@
-import { InteractiveSidebarItem, RawSidebarItem, SidebarSortType } from "types"
+import { Sidebar } from "types"
 
 type Options = {
-  items: RawSidebarItem[]
-  type?: SidebarSortType
+  items: Sidebar.RawSidebarItem[]
+  type?: Sidebar.SidebarSortType
 }
 
 export const sortSidebarItems = ({
   items,
   type = "none",
-}: Options): RawSidebarItem[] => {
+}: Options): Sidebar.RawSidebarItem[] => {
   switch (type) {
     case "alphabetize":
       return alphabetizeSidebarItems(items)
@@ -17,9 +17,11 @@ export const sortSidebarItems = ({
   }
 }
 
-const alphabetizeSidebarItems = (items: RawSidebarItem[]): RawSidebarItem[] => {
-  const segments: RawSidebarItem[][] = []
-  let currentSegment: RawSidebarItem[] = []
+const alphabetizeSidebarItems = (
+  items: Sidebar.RawSidebarItem[]
+): Sidebar.RawSidebarItem[] => {
+  const segments: Sidebar.RawSidebarItem[][] = []
+  let currentSegment: Sidebar.RawSidebarItem[] = []
 
   items.forEach((item) => {
     if (item.type === "separator") {
@@ -41,7 +43,7 @@ const alphabetizeSidebarItems = (items: RawSidebarItem[]): RawSidebarItem[] => {
     .map((segment) => {
       return segment[0].type === "separator"
         ? segment
-        : (segment as InteractiveSidebarItem[]).sort((a, b) =>
+        : (segment as Sidebar.InteractiveSidebarItem[]).sort((a, b) =>
             a.title.localeCompare(b.title)
           )
     })

www/packages/build-scripts/src/utils/validate-sidebar-unique-ids.ts

@@ -0,0 +1,22 @@
+import { Sidebar } from "types"
+
+export const validateSidebarUniqueIds = (
+  sidebars: (Sidebar.RawSidebar | Sidebar.SidebarItemSidebar)[],
+  sidebarIds = new Set<string>()
+): void => {
+  for (const sidebar of sidebars) {
+    if (sidebarIds.has(sidebar.sidebar_id)) {
+      throw new Error(`Duplicate sidebar item id found: ${sidebar.sidebar_id}`)
+    }
+
+    sidebarIds.add(sidebar.sidebar_id)
+
+    const children = (
+      "items" in sidebar ? sidebar.items : sidebar.children || []
+    ).filter(
+      (child) => child.type === "sidebar"
+    ) as Sidebar.SidebarItemSidebar[]
+
+    validateSidebarUniqueIds(children, sidebarIds)
+  }
+}