docs: generate sidebar for main docs (#11139)

www/packages/build-scripts/src/generate-sidebar.ts

@@ -4,11 +4,16 @@ import path from "path"
 import { getSidebarItemLink, sidebarAttachHrefCommonOptions } from "./index.js"
 import getCoreFlowsRefSidebarChildren from "./utils/get-core-flows-ref-sidebar-children.js"
 import { parseTags } from "./utils/parse-tags.js"
+import numberSidebarItems from "./utils/number-sidebar-items.js"
 
 export type ItemsToAdd = SidebarItem & {
   sidebar_position?: number
 }
 
+type GenerateSidebarOptions = {
+  addNumbering?: boolean
+}
+
 const customGenerators: Record<string, () => Promise<ItemsToAdd[]>> = {
   "core-flows": getCoreFlowsRefSidebarChildren,
 }
@@ -158,8 +163,11 @@ async function checkItem(item: RawSidebarItem): Promise<RawSidebarItem> {
   return item
 }
 
-async function checkItems(items: RawSidebarItem[]): Promise<RawSidebarItem[]> {
-  return (
+async function checkItems(
+  items: RawSidebarItem[],
+  options?: GenerateSidebarOptions
+): Promise<RawSidebarItem[]> {
+  const updatedItems = (
     await Promise.all(items.map(async (item) => await checkItem(item)))
   ).filter((item) => {
     if (item.type !== "category" && item.type !== "sub-category") {
@@ -168,13 +176,22 @@ async function checkItems(items: RawSidebarItem[]): Promise<RawSidebarItem[]> {
 
     return (item.children?.length || 0) > 0
   })
+
+  if (options?.addNumbering) {
+    return numberSidebarItems(updatedItems)
+  }
+
+  return updatedItems
 }
 
-export async function generateSidebar(sidebar: RawSidebarItem[]) {
+export async function generateSidebar(
+  sidebar: RawSidebarItem[],
+  options?: GenerateSidebarOptions
+): Promise<void> {
   const path = await import("path")
   const { writeFileSync } = await import("fs")
 
-  const normalizedSidebar = await checkItems(sidebar)
+  const normalizedSidebar = await checkItems(sidebar, options)
 
   const generatedDirPath = path.resolve("generated")
 

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

@@ -0,0 +1,59 @@
+import { InteractiveSidebarItem, SidebarItem, SidebarItemCategory } from "types"
+
+export default function numberSidebarItems(
+  sidebarItems: SidebarItem[],
+  numbering = [1]
+): SidebarItem[] {
+  if (!numbering.length) {
+    numbering.push(1)
+  }
+  const isTopItems = numbering.length === 1
+  const numberedItems: SidebarItem[] = []
+  let parentItem: InteractiveSidebarItem | undefined
+  sidebarItems.forEach((item) => {
+    if (item.type === "separator") {
+      ;(parentItem?.children || numberedItems).push(item)
+      return
+    }
+
+    // append current number to the item's title
+    item.chapterTitle = `${numbering.join(".")}. ${
+      item.chapterTitle?.trim() || item.title?.trim()
+    }`
+    item.title = item.title.trim()
+
+    if (isTopItems) {
+      // Add chapter category
+      numberedItems.push(
+        item.type === "category"
+          ? {
+              ...item,
+              title: item.chapterTitle,
+            }
+          : {
+              type: "category",
+              title: item.chapterTitle,
+              children: [],
+              loaded: true,
+              initialOpen: false,
+            }
+      )
+
+      parentItem = numberedItems[
+        numberedItems.length - 1
+      ] as SidebarItemCategory
+    }
+
+    if (item.children) {
+      item.children = numberSidebarItems(item.children, [...numbering, 1])
+    }
+
+    if (item.type !== "category" || !isTopItems) {
+      ;(parentItem?.children || numberedItems).push(item)
+    }
+
+    numbering[numbering.length - 1]++
+  })
+
+  return numberedItems
+}