docs: redesign sidebar (#8408)

* initial changes

* redesign the sidebar + nav drawer

* changes to sidebar items

* finish up sidebar redesign

* support new sidebar in resources

* general fixes

* integrate in ui

* support api reference

* refactor

* integrate in user guide

* docs: fix build errors

* fix user guide build

* more refactoring

* added banner

* added bottom logo + icon

* fix up sidebar

* fix up paddings

* fix shadow bottom

* docs: add table of content (#8445)

* add toc types

* implement toc functionality

* finished toc redesign

* redesigned table of content

* mobile fixes

* truncate text in toc

* mobile fixes

* merge fixes

* implement redesign

* add hide sidebar

* add menu action item

* finish up hide sidebar design

* implement redesign in resources

* integrate in api reference

* integrate changes in ui

* fixes to api reference scrolling

* fix build error

* fix build errors

* fixes

* fixes to sidebar

* general fixes

* fix active category not closing

* fix long titles

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

@@ -1,10 +1,10 @@
-import type { RawSidebarItemType } from "types"
+import type { RawSidebarItem, SidebarItem } from "types"
 import { existsSync, mkdirSync, readdirSync, statSync } from "fs"
 import path from "path"
 import { getSidebarItemLink, sidebarAttachHrefCommonOptions } from "./index.js"
 import getCoreFlowsRefSidebarChildren from "./utils/get-core-flows-ref-sidebar-children.js"
 
-export type ItemsToAdd = RawSidebarItemType & {
+export type ItemsToAdd = SidebarItem & {
   sidebar_position?: number
 }
 
@@ -37,19 +37,17 @@ async function getSidebarItems(
         true
       )
       if (nested && newItems.length > 1) {
-        items.push(
-          ...sidebarAttachHrefCommonOptions([
-            {
-              title:
-                fileBasename.charAt(0).toUpperCase() +
-                fileBasename.substring(1),
-              hasTitleStyling: true,
-              children: newItems,
-            },
-          ])
-        )
+        items.push({
+          type: "sub-category",
+          title:
+            fileBasename.charAt(0).toUpperCase() + fileBasename.substring(1),
+          children: newItems,
+          loaded: true,
+        })
       } else {
-        items.push(...sidebarAttachHrefCommonOptions(newItems))
+        items.push(
+          ...(sidebarAttachHrefCommonOptions(newItems) as ItemsToAdd[])
+        )
       }
       continue
     }
@@ -69,7 +67,11 @@ async function getSidebarItems(
     mainPageIndex = items.length - 1
   }
 
-  if (mainPageIndex !== -1 && items.length > 1) {
+  if (
+    mainPageIndex !== -1 &&
+    items.length > 1 &&
+    items[0].type !== "separator"
+  ) {
     // push all other items to be children of that page.
     const mainPageChildren = [
       ...items.splice(0, mainPageIndex),
@@ -84,9 +86,19 @@ async function getSidebarItems(
   return items
 }
 
-async function checkItem(
-  item: RawSidebarItemType
-): Promise<RawSidebarItemType> {
+async function checkItem(item: RawSidebarItem): Promise<RawSidebarItem> {
+  if (!item.type) {
+    throw new Error(
+      `ERROR: The following item doesn't have a type: ${JSON.stringify(
+        item,
+        undefined,
+        2
+      )}`
+    )
+  }
+  if (item.type === "separator") {
+    return item
+  }
   if (item.autogenerate_path) {
     item.children = (await getSidebarItems(item.autogenerate_path)).map(
       (child) => {
@@ -109,7 +121,7 @@ async function checkItem(
   return item
 }
 
-export async function generateSidebar(sidebar: RawSidebarItemType[]) {
+export async function generateSidebar(sidebar: RawSidebarItem[]) {
   const path = await import("path")
   const { writeFileSync } = await import("fs")
 

www/packages/build-scripts/src/utils/get-core-flows-ref-sidebar-children.ts

@@ -14,6 +14,19 @@ export default async function getCoreFlowsRefSidebarChildren(): Promise<
 
   const sidebarItems: ItemsToAdd[] = []
 
+  sidebarItems.push(
+    {
+      type: "link",
+      title: "Overview",
+      path: "/medusa-workflows-reference",
+      loaded: true,
+      isPathHref: true,
+    },
+    {
+      type: "separator",
+    }
+  )
+
   for (const directory of directories) {
     if (
       !directory.isDirectory() ||
@@ -66,21 +79,28 @@ export default async function getCoreFlowsRefSidebarChildren(): Promise<
 
     if (workflowItems.length || stepItems.length) {
       const item: ItemsToAdd = {
+        type: "category",
         title: directory.name.replaceAll("_", " "),
         children: [],
+        loaded: true,
+        initialOpen: false,
       }
 
       if (workflowItems.length) {
         item.children!.push({
+          type: "sub-category",
           title: "Workflows",
           children: workflowItems,
+          loaded: true,
         })
       }
 
       if (stepItems.length) {
         item.children!.push({
+          type: "sub-category",
           title: "Steps",
           children: stepItems,
+          loaded: true,
         })
       }
 

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

@@ -3,6 +3,7 @@ import { ItemsToAdd, sidebarAttachHrefCommonOptions } from "../index.js"
 import { readFileSync } from "fs"
 import findMetadataTitle from "./find-metadata-title.js"
 import findPageHeading from "./find-page-heading.js"
+import { InteractiveSidebarItem } from "types"
 
 export async function getSidebarItemLink({
   filePath,
@@ -24,6 +25,7 @@ export async function getSidebarItemLink({
 
   const newItem = sidebarAttachHrefCommonOptions([
     {
+      type: "link",
       path:
         frontmatter.slug ||
         filePath.replace(basePath, "").replace(`/${fileBasename}`, ""),
@@ -33,7 +35,7 @@ export async function getSidebarItemLink({
         findPageHeading(fileContent) ||
         "",
     },
-  ])[0]
+  ])[0] as InteractiveSidebarItem
 
   return {
     ...newItem,

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

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