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/apps/api-reference/app/layout.tsx

@@ -58,9 +58,6 @@ export default function RootLayout({
       gaId={process.env.NEXT_PUBLIC_GA_ID}
     >
       <WideLayout
-        sidebarProps={{
-          expandItems: false,
-        }}
         showToc={false}
         showBreadcrumbs={false}
         ProvidersComponent={Providers}

www/apps/api-reference/components/MDXComponents/H2/index.tsx

@@ -3,13 +3,13 @@
 import { useScrollController, useSidebar, H2 as UiH2 } from "docs-ui"
 import { useEffect, useMemo, useRef, useState } from "react"
 import getSectionId from "../../../utils/get-section-id"
-import { SidebarItem } from "types"
+import { Sidebar } from "types"
 
 type H2Props = React.HTMLAttributes<HTMLHeadingElement>
 
 const H2 = ({ children, ...props }: H2Props) => {
   const headingRef = useRef<HTMLHeadingElement>(null)
-  const { activePath, addItems, removeItems } = useSidebar()
+  const { activePath, addItems, removeItems, shownSidebar } = useSidebar()
   const { scrollableElement, scrollToElement } = useScrollController()
   const [scrolledFirstTime, setScrolledFirstTime] = useState(false)
 
@@ -29,7 +29,10 @@ const H2 = ({ children, ...props }: H2Props) => {
   }, [scrollableElement, headingRef, id])
 
   useEffect(() => {
-    const item: SidebarItem[] = [
+    if (!shownSidebar) {
+      return
+    }
+    const items: Sidebar.SidebarItem[] = [
       {
         type: "link",
         path: `${id}`,
@@ -37,12 +40,17 @@ const H2 = ({ children, ...props }: H2Props) => {
         loaded: true,
       },
     ]
-    addItems(item)
+    addItems(items, {
+      sidebar_id: shownSidebar.sidebar_id,
+    })
 
     return () => {
-      removeItems(item)
+      removeItems({
+        items,
+        sidebar_id: shownSidebar.sidebar_id,
+      })
     }
-  }, [id])
+  }, [id, shownSidebar?.sidebar_id])
 
   return (
     <UiH2 {...props} id={id} passRef={headingRef}>

www/apps/api-reference/components/Tags/Operation/index.tsx

@@ -60,11 +60,12 @@ const TagOperation = ({
   }, [isBrowser, scrollableElement])
 
   const scrollIntoView = useCallback(() => {
-    if (!isBrowser) {
+    if (!isBrowser || !nodeRef.current) {
+      // repeat timeout
+      setTimeout(scrollIntoView, 200)
       return
     }
-
-    if (nodeRef.current && !checkElementInViewport(nodeRef.current, 0)) {
+    if (!checkElementInViewport(nodeRef.current, 0)) {
       const elm = nodeRef.current as HTMLElement
       scrollToTop(
         elm.offsetTop + (elm.offsetParent as HTMLElement)?.offsetTop,

www/apps/api-reference/components/Tags/Paths/index.tsx

@@ -1,8 +1,7 @@
 "use client"
 
-import type { OpenAPIV3 } from "openapi-types"
-import type { Operation, PathsObject } from "@/types/openapi"
-import { useSidebar } from "docs-ui"
+import type { Operation, PathsObject, TagObject } from "@/types/openapi"
+import { findSidebarItem, useSidebar } from "docs-ui"
 import { Fragment, Suspense, useEffect } from "react"
 import dynamic from "next/dynamic"
 import type { TagOperationProps } from "../Operation"
@@ -10,32 +9,41 @@ import clsx from "clsx"
 import getTagChildSidebarItems from "@/utils/get-tag-child-sidebar-items"
 import { useLoading } from "@/providers/loading"
 import DividedLoading from "@/components/DividedLoading"
-import { SidebarItemSections, SidebarItem, SidebarItemCategory } from "types"
+import { Sidebar } from "types"
 
 const TagOperation = dynamic<TagOperationProps>(
   async () => import("../Operation")
 ) as React.FC<TagOperationProps>
 
 export type TagPathsProps = {
-  tag: OpenAPIV3.TagObject
+  tag: TagObject
   paths: PathsObject
 } & React.HTMLAttributes<HTMLDivElement>
 
 const TagPaths = ({ tag, className, paths }: TagPathsProps) => {
-  const { items, addItems, findItemInSection } = useSidebar()
+  const { shownSidebar, addItems } = useSidebar()
   const { loading } = useLoading()
 
   useEffect(() => {
+    if (!shownSidebar) {
+      return
+    }
+
     if (paths) {
-      const parentItem = findItemInSection(
-        items[SidebarItemSections.DEFAULT],
-        { title: tag.name },
-        false
-      ) as SidebarItemCategory
-      const pathItems: SidebarItem[] = getTagChildSidebarItems(paths)
-      if ((parentItem?.children?.length || 0) < pathItems.length) {
+      const parentItem = findSidebarItem({
+        sidebarItems:
+          "items" in shownSidebar
+            ? shownSidebar.items
+            : shownSidebar.children || [],
+        item: { title: tag.name, type: "category" },
+        checkChildren: false,
+      }) as Sidebar.SidebarItemCategory
+      const pathItems: Sidebar.SidebarItem[] = getTagChildSidebarItems(paths)
+      const targetLength =
+        pathItems.length + (tag["x-associatedSchema"] ? 1 : 0)
+      if ((parentItem.children?.length || 0) < targetLength) {
         addItems(pathItems, {
-          section: SidebarItemSections.DEFAULT,
+          sidebar_id: shownSidebar.sidebar_id,
           parent: {
             type: "category",
             title: tag.name,
@@ -46,7 +54,7 @@ const TagPaths = ({ tag, className, paths }: TagPathsProps) => {
       }
     }
     // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [paths])
+  }, [paths, shownSidebar?.sidebar_id])
 
   return (
     <Suspense>

www/apps/api-reference/components/Tags/Section/Schema/index.tsx

@@ -1,6 +1,6 @@
 "use client"
 
-import { Suspense, useEffect, useMemo, useRef } from "react"
+import { Suspense, useEffect, useMemo } from "react"
 import { SchemaObject } from "../../../../types/openapi"
 import TagOperationParameters from "../../Operation/Parameters"
 import {
@@ -13,7 +13,6 @@ import {
   useScrollController,
   useSidebar,
 } from "docs-ui"
-import { SidebarItemSections } from "types"
 import getSectionId from "../../../../utils/get-section-id"
 import DividedLayout from "../../../../layouts/Divided"
 import SectionContainer from "../../../Section/Container"
@@ -30,7 +29,7 @@ export type TagSectionSchemaProps = {
 }
 
 const TagSectionSchema = ({ schema, tagName }: TagSectionSchemaProps) => {
-  const { addItems, setActivePath, activePath } = useSidebar()
+  const { addItems, setActivePath, activePath, shownSidebar } = useSidebar()
   const { displayedArea } = useArea()
   const formattedName = useMemo(
     () => singular(tagName).replaceAll(" ", ""),
@@ -58,6 +57,9 @@ const TagSectionSchema = ({ schema, tagName }: TagSectionSchemaProps) => {
   }, [isBrowser, scrollableElement])
 
   useEffect(() => {
+    if (!shownSidebar) {
+      return
+    }
     addItems(
       [
         {
@@ -69,7 +71,7 @@ const TagSectionSchema = ({ schema, tagName }: TagSectionSchemaProps) => {
         },
       ],
       {
-        section: SidebarItemSections.DEFAULT,
+        sidebar_id: shownSidebar.sidebar_id,
         parent: {
           type: "category",
           title: tagName,
@@ -80,7 +82,7 @@ const TagSectionSchema = ({ schema, tagName }: TagSectionSchemaProps) => {
       }
     )
     // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [formattedName])
+  }, [formattedName, shownSidebar?.sidebar_id])
 
   useEffect(() => {
     if (!isBrowser) {

www/apps/api-reference/components/Tags/Section/index.tsx

@@ -85,13 +85,15 @@ const TagSectionComponent = ({ tag }: TagSectionProps) => {
   )
 
   useEffect(() => {
-    if (!isBrowser) {
+    if (!isBrowser || !activePath || !activePath.includes(slugTagName)) {
       return
     }
 
-    if (activePath && activePath.includes(slugTagName)) {
     const tagName = activePath.split("_")
-      if (tagName.length === 1 && tagName[0] === slugTagName) {
+    if (tagName[0] !== slugTagName) {
+      return
+    }
+    if (tagName.length === 1) {
       const elm = document.getElementById(tagName[0])
       if (elm && !checkElementInViewport(elm, 0)) {
         scrollToTop(
@@ -99,10 +101,9 @@ const TagSectionComponent = ({ tag }: TagSectionProps) => {
           0
         )
       }
-      } else if (tagName.length > 1 && tagName[0] === slugTagName) {
+    } else if (tagName.length > 1) {
       setLoadData(true)
     }
-    }
   }, [slugTagName, activePath, isBrowser])
 
   return (

www/apps/api-reference/config/index.ts

@@ -8,8 +8,11 @@ export const config: DocsConfig = {
   baseUrl,
   basePath: process.env.NEXT_PUBLIC_BASE_PATH,
   // sidebar is auto generated
-  sidebar: {
-    default: [
+  sidebars: [
+    {
+      sidebar_id: "api-ref",
+      title: "API Reference",
+      items: [
         {
           type: "link",
           title: "Introduction",
@@ -17,8 +20,8 @@ export const config: DocsConfig = {
           loaded: true,
         },
       ],
-    mobile: [],
     },
+  ],
   project: {
     title: "API Reference",
     key: "api-reference",

www/apps/api-reference/providers/base-specs.tsx

@@ -2,7 +2,7 @@
 
 import { ExpandedDocument, SecuritySchemeObject } from "@/types/openapi"
 import { ReactNode, createContext, useContext, useEffect, useMemo } from "react"
-import { SidebarItem, SidebarItemSections } from "types"
+import { Sidebar } from "types"
 import getSectionId from "../utils/get-section-id"
 import getTagChildSidebarItems from "../utils/get-tag-child-sidebar-items"
 import { useRouter } from "next/navigation"
@@ -22,7 +22,8 @@ type BaseSpecsProviderProps = {
 
 const BaseSpecsProvider = ({ children, baseSpecs }: BaseSpecsProviderProps) => {
   const router = useRouter()
-  const { activePath, addItems, setActivePath, resetItems } = useSidebar()
+  const { activePath, addItems, setActivePath, resetItems, shownSidebar } =
+    useSidebar()
 
   const getSecuritySchema = (
     securityName: string
@@ -48,7 +49,7 @@ const BaseSpecsProvider = ({ children, baseSpecs }: BaseSpecsProviderProps) => {
       return []
     }
 
-    const itemsToAdd: SidebarItem[] = [
+    const itemsToAdd: Sidebar.SidebarItem[] = [
       {
         type: "separator",
       },
@@ -67,6 +68,7 @@ const BaseSpecsProvider = ({ children, baseSpecs }: BaseSpecsProviderProps) => {
         children: childItems,
         loaded: childItems.length > 0,
         showLoadingIfEmpty: true,
+        initialOpen: false,
         onOpen: () => {
           if (location.hash !== tagPathName) {
             router.push(`#${tagPathName}`, {
@@ -84,14 +86,14 @@ const BaseSpecsProvider = ({ children, baseSpecs }: BaseSpecsProviderProps) => {
   }, [baseSpecs])
 
   useEffect(() => {
-    if (!itemsToAdd.length) {
+    if (!itemsToAdd.length || !shownSidebar) {
       return
     }
 
     addItems(itemsToAdd, {
-      section: SidebarItemSections.DEFAULT,
+      sidebar_id: shownSidebar.sidebar_id,
     })
-  }, [itemsToAdd])
+  }, [itemsToAdd, shownSidebar?.sidebar_id])
 
   useEffect(() => {
     return () => {

www/apps/api-reference/providers/page-title.tsx

@@ -3,7 +3,7 @@
 import { createContext, useEffect } from "react"
 import { useSidebar } from "docs-ui"
 import { useArea } from "./area"
-import { SidebarItemLink } from "types"
+import { Sidebar } from "types"
 
 const PageTitleContext = createContext(null)
 
@@ -27,7 +27,7 @@ const PageTitleProvider = ({ children }: PageTitleProviderProps) => {
         // find the child that matches the active path
         const item = activeItem?.children?.find(
           (i) => i.type === "link" && i.path === activePath
-        ) as SidebarItemLink
+        ) as Sidebar.SidebarItemLink
         if (item) {
           document.title = `${item.title} - ${titleSuffix}`
         }

www/apps/api-reference/providers/sidebar.tsx

@@ -20,10 +20,12 @@ const SidebarProvider = ({ children }: SidebarProviderProps) => {
       isLoading={isLoading}
       setIsLoading={setIsLoading}
       shouldHandleHashChange={true}
+      shouldHandlePathChange={false}
       scrollableElement={scrollableElement}
-      initialItems={config.sidebar}
-      persistState={false}
-      projectName="api"
+      sidebars={config.sidebars}
+      persistCategoryState={false}
+      disableActiveTransition={false}
+      isSidebarStatic={false}
     >
       {children}
     </UiSidebarProvider>

www/apps/api-reference/utils/get-tag-child-sidebar-items.tsx

@@ -1,9 +1,9 @@
-import type { SidebarItem } from "types"
 import type { Operation, PathsObject } from "@/types/openapi"
 import type { OpenAPIV3 } from "openapi-types"
 import dynamic from "next/dynamic"
 import type { MethodLabelProps } from "@/components/MethodLabel"
 import getSectionId from "./get-section-id"
+import { Sidebar } from "types"
 
 const MethodLabel = dynamic<MethodLabelProps>(
   async () => import("../components/MethodLabel")
@@ -11,8 +11,8 @@ const MethodLabel = dynamic<MethodLabelProps>(
 
 export default function getTagChildSidebarItems(
   paths: PathsObject
-): SidebarItem[] {
-  const items: SidebarItem[] = []
+): Sidebar.SidebarItem[] {
+  const items: Sidebar.SidebarItem[] = []
   Object.entries(paths).forEach(([, operations]) => {
     Object.entries(operations).map(([method, operation]) => {
       const definedOperation = operation as Operation

www/apps/book/app/learn/layout.tsx

@@ -8,13 +8,7 @@ export default function RootLayout({
   children: React.ReactNode
 }) {
   return (
-    <TightLayout
-      sidebarProps={{
-        expandItems: true,
-      }}
-      ProvidersComponent={Providers}
-      footerComponent={<Footer />}
-    >
+    <TightLayout ProvidersComponent={Providers} footerComponent={<Footer />}>
       {children}
     </TightLayout>
   )

www/apps/book/app/not-found.tsx

@@ -6,13 +6,7 @@ import Footer from "../components/Footer"
 
 const NotFoundPage = () => {
   return (
-    <TightLayout
-      sidebarProps={{
-        expandItems: true,
-      }}
-      footerComponent={<Footer />}
-      ProvidersComponent={Providers}
-    >
+    <TightLayout footerComponent={<Footer />} ProvidersComponent={Providers}>
       {/* @ts-ignore React v19 doesn't recognize MDX import as component */}
       <NotFoundContent />
     </TightLayout>

www/apps/book/config/index.ts

@@ -1,6 +1,6 @@
-import { DocsConfig } from "types"
-import { sidebarConfig } from "./sidebar"
+import { DocsConfig, Sidebar } from "types"
 import { globalConfig } from "docs-ui"
+import { generatedSidebars } from "../generated/sidebar.mjs"
 
 const baseUrl = process.env.NEXT_PUBLIC_BASE_URL || "http://localhost:3000"
 
@@ -9,10 +9,18 @@ export const config: DocsConfig = {
   titleSuffix: "Medusa v2 Documentation",
   baseUrl,
   basePath: process.env.NEXT_PUBLIC_BASE_PATH,
-  sidebar: sidebarConfig,
+  sidebars: generatedSidebars as Sidebar.Sidebar[],
   project: {
     title: "Documentation",
     key: "book",
   },
   logo: `${process.env.NEXT_PUBLIC_BASE_PATH}/images/logo.png`,
+  breadcrumbOptions: {
+    startItems: [
+      {
+        title: "Documentation",
+        link: "/",
+      },
+    ],
+  },
 }

www/apps/book/config/sidebar.tsx

@@ -1,8 +0,0 @@
-import type { SidebarConfig } from "@/types"
-import { generatedSidebar } from "../generated/sidebar.mjs"
-import { SidebarItem } from "types"
-
-export const sidebarConfig: SidebarConfig = {
-  default: generatedSidebar as SidebarItem[],
-  mobile: [],
-}

www/apps/book/generated/sidebar.mjs

@@ -1,7 +1,12 @@
-export const generatedSidebar = [
+export const generatedSidebars = [
+  {
+    "sidebar_id": "docs",
+    "title": "Get Started",
+    "items": [
       {
         "loaded": true,
         "isPathHref": true,
+        "initialOpen": false,
         "type": "category",
         "title": "1. Get Started",
         "children": [
@@ -42,6 +47,7 @@ export const generatedSidebar = [
       {
         "loaded": true,
         "isPathHref": true,
+        "initialOpen": false,
         "type": "category",
         "title": "2. Customization Tutorial",
         "children": [
@@ -226,6 +232,7 @@ export const generatedSidebar = [
       {
         "loaded": true,
         "isPathHref": true,
+        "initialOpen": false,
         "type": "category",
         "title": "3. Framework",
         "children": [
@@ -905,6 +912,7 @@ export const generatedSidebar = [
       {
         "loaded": true,
         "isPathHref": true,
+        "initialOpen": false,
         "type": "category",
         "title": "4. Admin Development",
         "children": [
@@ -983,6 +991,8 @@ export const generatedSidebar = [
         "number": "4."
       },
       {
+        "loaded": true,
+        "isPathHref": true,
         "type": "category",
         "title": "5. Storefront",
         "children": [
@@ -994,16 +1004,15 @@ export const generatedSidebar = [
             "title": "Storefront Development",
             "chapterTitle": "5. Storefront",
             "children": [],
-        "childrenSameLevel": true,
             "number": "5."
           }
         ],
-    "loaded": true,
         "initialOpen": false
       },
       {
         "loaded": true,
         "isPathHref": true,
+        "initialOpen": false,
         "type": "category",
         "title": "6. Configurations",
         "children": [
@@ -1034,6 +1043,7 @@ export const generatedSidebar = [
       {
         "loaded": true,
         "isPathHref": true,
+        "initialOpen": false,
         "type": "category",
         "title": "7. Debugging & Testing",
         "children": [
@@ -1124,6 +1134,8 @@ export const generatedSidebar = [
         "number": "7."
       },
       {
+        "loaded": true,
+        "isPathHref": true,
         "type": "category",
         "title": "8. Production",
         "children": [
@@ -1156,16 +1168,15 @@ export const generatedSidebar = [
                 "number": "8.2."
               }
             ],
-        "childrenSameLevel": true,
             "number": "8."
           }
         ],
-    "loaded": true,
         "initialOpen": false
       },
       {
         "loaded": true,
         "isPathHref": true,
+        "initialOpen": false,
         "type": "category",
         "title": "9. Upgrade",
         "children": [
@@ -1196,6 +1207,7 @@ export const generatedSidebar = [
       {
         "loaded": true,
         "isPathHref": true,
+        "initialOpen": false,
         "type": "category",
         "title": "10. Resources",
         "children": [
@@ -1209,7 +1221,7 @@ export const generatedSidebar = [
                 "loaded": true,
                 "isPathHref": true,
                 "type": "link",
-            "path": "/resources/contribution-guidelines/docs",
+                "path": "/learn/resources/contribution-guidelines/docs",
                 "title": "Docs",
                 "children": [],
                 "chapterTitle": "10.1.1. Docs",
@@ -1219,7 +1231,7 @@ export const generatedSidebar = [
                 "loaded": true,
                 "isPathHref": true,
                 "type": "link",
-            "path": "/resources//contribution-guidelines/admin-translations",
+                "path": "/learn/resources//contribution-guidelines/admin-translations",
                 "title": "Admin Translations",
                 "children": [],
                 "chapterTitle": "10.1.2. Admin Translations",
@@ -1233,7 +1245,7 @@ export const generatedSidebar = [
             "loaded": true,
             "isPathHref": true,
             "type": "link",
-        "path": "/resources/usage",
+            "path": "/learn/resources/usage",
             "title": "Usage",
             "children": [],
             "chapterTitle": "10.2. Usage",
@@ -1244,3 +1256,5 @@ export const generatedSidebar = [
         "number": "10."
       }
     ]
+  }
+]

www/apps/book/next.config.mjs

@@ -10,7 +10,7 @@ import {
 } from "remark-rehype-plugins"
 import path from "path"
 import redirects from "./utils/redirects.mjs"
-import { generatedSidebar } from "./generated/sidebar.mjs"
+import { generatedSidebars } from "./generated/sidebar.mjs"
 
 const withMDX = mdx({
   extension: /\.mdx?$/,
@@ -82,7 +82,7 @@ const withMDX = mdx({
       [
         pageNumberRehypePlugin,
         {
-          sidebar: generatedSidebar,
+          sidebar: generatedSidebars[0].items,
         },
       ],
     ],

www/apps/book/providers/sidebar.tsx

@@ -15,13 +15,8 @@ const SidebarProvider = ({ children }: SidebarProviderProps) => {
 
   return (
     <UiSidebarProvider
-      shouldHandlePathChange={true}
-      shouldHandleHashChange={false}
       scrollableElement={scrollableElement}
-      initialItems={config.sidebar}
-      staticSidebarItems={true}
-      disableActiveTransition={true}
-      projectName="docs"
+      sidebars={config.sidebars}
     >
       {children}
     </UiSidebarProvider>

www/apps/book/scripts/prepare.mjs

@@ -1,6 +1,6 @@
 import "dotenv/config"
 import path from "path"
-import { sidebar } from "../sidebar.mjs"
+import { sidebars } from "../sidebar.mjs"
 import {
   generateEditedDates,
   generateLlmsFull,
@@ -15,7 +15,7 @@ import {
 
 async function main() {
   await generateEditedDates()
-  await generateSidebar(sidebar, {
+  await generateSidebar(sidebars, {
     addNumbering: true,
   })
   const baseUrl =

www/apps/book/sidebar.mjs

@@ -1,7 +1,9 @@
-import { sidebarAttachHrefCommonOptions } from "./utils/sidebar-attach-common-options.mjs"
-
-/** @type {import('@/types').SidebarItem[]} */
-export const sidebar = sidebarAttachHrefCommonOptions([
+/** @type {import("types").Sidebar.Sidebar[]} */
+export const sidebars = [
+  {
+    sidebar_id: "docs",
+    title: "Get Started",
+    items: [
       {
         type: "category",
         title: "Get Started",
@@ -633,21 +635,23 @@ export const sidebar = sidebarAttachHrefCommonOptions([
             children: [
               {
                 type: "link",
-            path: "/resources/contribution-guidelines/docs",
+                path: "/learn/resources/contribution-guidelines/docs",
                 title: "Docs",
               },
               {
                 type: "link",
-            path: "/resources//contribution-guidelines/admin-translations",
+                path: "/learn/resources//contribution-guidelines/admin-translations",
                 title: "Admin Translations",
               },
             ],
           },
           {
             type: "link",
-        path: "/resources/usage",
+            path: "/learn/resources/usage",
             title: "Usage",
           },
         ],
       },
-])
+    ],
+  },
+]

www/apps/book/types/index.d.ts

@@ -1,8 +0,0 @@
-import { SidebarSectionItems, SidebarItem as SidebarItemType } from "types"
-
-export declare type SidebarItem = SidebarItemType & {
-  isSoon: boolean
-  number?: string
-}
-
-export declare type SidebarConfig = SidebarSectionItems

www/apps/book/utils/sidebar-attach-common-options.mjs

@@ -1,31 +0,0 @@
-/** @type {Partial<import("@/types").SidebarItem[]>} */
-const commonOptions = {
-  loaded: true,
-  isPathHref: true,
-}
-
-/**
- *
- * @param {import("@/types").SidebarItem[]} sidebar
- * @param {boolean} nested
- * @returns {import("@/types").SidebarItem[]}
- */
-export function sidebarAttachHrefCommonOptions(sidebar, nested = false) {
-  return sidebar.map((item) => {
-    if (item.type === "separator") {
-      return item
-    }
-
-    const updatedItem = {
-      ...commonOptions,
-      ...item,
-      children: sidebarAttachHrefCommonOptions(item.children || [], true),
-    }
-
-    if (updatedItem.type !== "category" && !nested) {
-      updatedItem.childrenSameLevel = true
-    }
-
-    return updatedItem
-  })
-}

www/apps/resources/app/admin-components/page.mdx

@@ -16,7 +16,7 @@ Refer to the [Medusa UI documentation](!ui!) for a full list of components.
 
 Use these components to set the layout of your UI route.
 
-<ChildDocs showItems={["Layouts"]} onlyTopLevel={false} />
+<ChildDocs showItems={["Layouts"]} onlyTopLevel={false} hideTitle />
 
 ---
 
@@ -24,4 +24,4 @@ Use these components to set the layout of your UI route.
 
 Use these components in your widgets and UI routes.
 
-<ChildDocs showItems={["Components"]} onlyTopLevel={false} />
+<ChildDocs showItems={["Components"]} onlyTopLevel={false} hideTitle />

www/apps/resources/app/layout.tsx

@@ -63,13 +63,7 @@ export default function RootLayout({
       htmlClassName={clsx(inter.variable, robotoMono.variable)}
       gaId={process.env.NEXT_PUBLIC_GA_ID}
     >
-      <TightLayout
-        sidebarProps={{
-          expandItems: true,
-        }}
-        ProvidersComponent={Providers}
-        footerComponent={<Footer />}
-      >
+      <TightLayout ProvidersComponent={Providers} footerComponent={<Footer />}>
         {children}
       </TightLayout>
     </BareboneLayout>

www/apps/resources/app/recipes/page.mdx

@@ -8,4 +8,4 @@ export const metadata = {
 
 This section of the documentation provides recipes for common use cases with example implementations.
 
-<ChildDocs onlyTopLevel />
+<ChildDocs onlyTopLevel hideItems={["Overview"]} />

www/apps/resources/app/storefront-development/page.mdx

@@ -20,4 +20,4 @@ You can build your storefront from scratch, or built it on top of the [Next.js S
 
 ---
 
-<ChildDocs hideItems={["General"]} />
+<ChildDocs hideItems={["General", "Overview"]} />

www/apps/resources/app/troubleshooting/page.mdx

@@ -12,4 +12,4 @@ The following troubleshooting guides are intended for technical users. If you're
 
 </Note>
 
-<ChildDocs />
+<ChildDocs hideItems={["Overview"]} />

www/apps/resources/components/CommerceModuleSections/index.tsx

@@ -12,7 +12,7 @@ export const CommerceModuleSections = () => {
       showItems: ["Server Guides"],
       defaultItemsPerRow: 2,
     })
-  if (serverGuideItems?.default.length) {
+  if (serverGuideItems?.length) {
     guideComponents.push(serverGuidesComponent)
   }
   const { items: storefrontGuideItems, component: storefrontGuidesComponent } =
@@ -20,7 +20,7 @@ export const CommerceModuleSections = () => {
       showItems: ["Storefront Guides"],
       defaultItemsPerRow: 2,
     })
-  if (storefrontGuideItems?.default.length) {
+  if (storefrontGuideItems?.length) {
     guideComponents.push(storefrontGuidesComponent)
   }
   const { items: adminGuideItems, component: adminGuidesComponent } =
@@ -28,7 +28,7 @@ export const CommerceModuleSections = () => {
       showItems: ["Admin Guides"],
       defaultItemsPerRow: 2,
     })
-  if (adminGuideItems?.default.length) {
+  if (adminGuideItems?.length) {
     guideComponents.push(adminGuidesComponent)
   }
   const { items: userGuideItems, component: userGuidesComponent } =
@@ -36,14 +36,14 @@ export const CommerceModuleSections = () => {
       showItems: ["User Guides"],
       defaultItemsPerRow: 2,
     })
-  if (userGuideItems?.default.length) {
+  if (userGuideItems?.length) {
     guideComponents.push(userGuidesComponent)
   }
   const { items: jsSdkItems, component: jsSdkComponent } = useChildDocs({
     showItems: ["JS SDK"],
     itemsPerRow: 2,
   })
-  if (jsSdkItems?.default.length) {
+  if (jsSdkItems?.length) {
     referenceComponents.push(jsSdkComponent)
   }
   const { items: referenceItems, component: referencesComponent } =
@@ -51,7 +51,7 @@ export const CommerceModuleSections = () => {
       showItems: ["References"],
       defaultItemsPerRow: 2,
     })
-  if (referenceItems?.default.length) {
+  if (referenceItems?.length) {
     referenceComponents.push(referencesComponent)
   }
 

www/apps/resources/config/index.ts

@@ -1,5 +1,5 @@
-import { DocsConfig, SidebarItem } from "types"
-import { generatedSidebar } from "../generated/sidebar.mjs"
+import { DocsConfig, Sidebar } from "types"
+import { generatedSidebars } from "../generated/sidebar.mjs"
 import { globalConfig } from "docs-ui"
 
 const baseUrl = process.env.NEXT_PUBLIC_BASE_URL || "http://localhost:3000"
@@ -9,16 +9,18 @@ export const config: DocsConfig = {
   titleSuffix: "Medusa Development Resources",
   baseUrl,
   basePath: process.env.NEXT_PUBLIC_BASE_PATH,
-  sidebar: {
-    default: generatedSidebar as SidebarItem[],
-    mobile: [],
-  },
+  sidebars: generatedSidebars as Sidebar.Sidebar[],
   project: {
     title: "Development Resources",
     key: "resources",
   },
   breadcrumbOptions: {
-    showCategories: true,
+    startItems: [
+      {
+        title: "Documentation",
+        link: baseUrl,
+      },
+    ],
   },
   logo: `${process.env.NEXT_PUBLIC_BASE_PATH}/images/logo.png`,
 }

www/apps/resources/generated/edit-dates.mjs

@@ -123,7 +123,7 @@ export const generatedEditDates = {
   "app/recipes/pos/page.mdx": "2025-02-26T12:42:52.949Z",
   "app/recipes/subscriptions/examples/standard/page.mdx": "2025-03-03T15:02:56.854Z",
   "app/recipes/subscriptions/page.mdx": "2025-02-26T12:31:49.933Z",
-  "app/recipes/page.mdx": "2024-07-11T15:56:41+00:00",
+  "app/recipes/page.mdx": "2025-03-07T07:48:28.203Z",
   "app/service-factory-reference/methods/create/page.mdx": "2024-07-31T17:01:33+03:00",
   "app/service-factory-reference/methods/delete/page.mdx": "2024-07-31T17:01:33+03:00",
   "app/service-factory-reference/methods/list/page.mdx": "2024-07-31T17:01:33+03:00",
@@ -177,7 +177,7 @@ export const generatedEditDates = {
   "app/storefront-development/regions/store-retrieve-region/page.mdx": "2024-12-19T16:36:22.800Z",
   "app/storefront-development/regions/page.mdx": "2024-06-09T15:19:09+02:00",
   "app/storefront-development/tips/page.mdx": "2024-12-19T16:36:32.938Z",
-  "app/storefront-development/page.mdx": "2024-12-10T09:23:20.666Z",
+  "app/storefront-development/page.mdx": "2025-03-07T07:49:27.809Z",
   "app/troubleshooting/cors-errors/page.mdx": "2024-05-03T17:36:38+03:00",
   "app/troubleshooting/create-medusa-app-errors/page.mdx": "2024-07-11T10:29:13+03:00",
   "app/troubleshooting/database-errors/page.mdx": "2024-05-03T17:36:38+03:00",
@@ -2101,7 +2101,7 @@ export const generatedEditDates = {
   "app/admin-components/components/json-view-section/page.mdx": "2024-10-07T11:15:58.833Z",
   "app/admin-components/components/section-row/page.mdx": "2024-10-07T11:15:58.832Z",
   "app/admin-components/components/table/page.mdx": "2025-03-03T14:53:37.952Z",
-  "app/admin-components/page.mdx": "2024-10-07T11:09:49.493Z",
+  "app/admin-components/page.mdx": "2025-03-07T08:00:46.960Z",
   "app/admin-components/layouts/single-column/page.mdx": "2024-10-07T11:16:06.435Z",
   "app/admin-components/layouts/two-column/page.mdx": "2024-10-07T11:16:10.092Z",
   "app/admin-components/components/forms/page.mdx": "2024-10-09T12:48:04.229Z",

www/apps/resources/generated/files-map.mjs

@@ -787,6 +787,10 @@ export const filesMap = [
     "filePath": "/www/apps/resources/app/examples/guides/custom-item-price/page.mdx",
     "pathname": "/examples/guides/custom-item-price"
   },
+  {
+    "filePath": "/www/apps/resources/app/examples/guides/quote-management/page.mdx",
+    "pathname": "/examples/guides/quote-management"
+  },
   {
     "filePath": "/www/apps/resources/app/examples/page.mdx",
     "pathname": "/examples"

www/apps/resources/providers/sidebar.tsx

@@ -14,13 +14,8 @@ const SidebarProvider = ({ children }: SidebarProviderProps) => {
 
   return (
     <UiSidebarProvider
-      shouldHandlePathChange={true}
-      shouldHandleHashChange={false}
       scrollableElement={scrollableElement}
-      initialItems={config.sidebar}
-      staticSidebarItems={true}
-      disableActiveTransition={true}
-      projectName="resources"
+      sidebars={config.sidebars}
     >
       {children}
     </UiSidebarProvider>

www/apps/resources/scripts/prepare.mjs

@@ -5,9 +5,9 @@ import { sidebar } from "../sidebar.mjs"
 
 async function main() {
   await generateSidebar(sidebar)
-  await generateSlugChanges()
-  await generateFilesMap()
-  await generateEditedDates()
+  // await generateSlugChanges()
+  // await generateFilesMap()
+  // await generateEditedDates()
 }
 
 void main()

www/apps/resources/sidebar.mjs

@@ -24,24 +24,21 @@ import { storefrontGuidesSidebar } from "./sidebars/storefront.mjs"
 import { taxSidebar } from "./sidebars/tax.mjs"
 import { troubleshootingSidebar } from "./sidebars/troubleshooting.mjs"
 import { userSidebar } from "./sidebars/user.mjs"
-import { sidebarAttachHrefCommonOptions } from "./utils/sidebar-attach-common-options.mjs"
 import { examplesSidebar } from "./sidebars/examples.mjs"
 
-/** @type {import('types').RawSidebarItem[]} */
-export const sidebar = sidebarAttachHrefCommonOptions([
+/** @type {import("types").Sidebar.RawSidebar[]} */
+export const sidebar = [
+  {
+    sidebar_id: "resources",
+    title: "Development Resources",
+    items: [
       {
         type: "link",
         path: "/",
         title: "Overview",
       },
       ...examplesSidebar,
-  {
-    type: "link",
-    path: "/recipes",
-    title: "Recipes",
-    isChildSidebar: true,
-    children: recipesSidebar,
-  },
+      ...recipesSidebar,
       {
         type: "separator",
       },
@@ -72,36 +69,10 @@ export const sidebar = sidebarAttachHrefCommonOptions([
           ...userSidebar,
         ],
       },
-  {
-    type: "link",
-    path: "/architectural-modules",
-    title: "Architectural Modules",
-    isChildSidebar: true,
-    sort_sidebar: "alphabetize",
-    children: architecturalModulesSidebar,
-  },
-  {
-    type: "link",
-    path: "/integrations",
-    title: "Integrations",
-    isChildSidebar: true,
-    sort_sidebar: "alphabetize",
-    children: integrationsSidebar,
-  },
-  {
-    type: "ref",
-    path: "/plugins",
-    title: "Plugins",
-    isChildSidebar: true,
-    children: pluginsSidebar,
-  },
-  {
-    type: "link",
-    path: "/storefront-development",
-    title: "Storefront Development",
-    isChildSidebar: true,
-    children: storefrontGuidesSidebar,
-  },
+      ...architecturalModulesSidebar,
+      ...integrationsSidebar,
+      ...pluginsSidebar,
+      ...storefrontGuidesSidebar,
       {
         type: "separator",
       },
@@ -115,16 +86,18 @@ export const sidebar = sidebarAttachHrefCommonOptions([
         title: "General",
         children: [
           {
-        type: "link",
-        path: "/references/medusa-config",
-        title: "Medusa Configurations",
-      },
+            type: "sidebar",
+            sidebar_id: "deployment-guides",
+            title: "Deployment Guides",
+            children: [
               {
                 type: "link",
                 path: "/deployment",
-        title: "Deployment Guides",
-        isChildSidebar: true,
-        children: [
+                title: "Overview",
+              },
+              {
+                type: "separator",
+              },
               {
                 type: "link",
                 title: "Medusa Cloud",
@@ -156,13 +129,7 @@ export const sidebar = sidebarAttachHrefCommonOptions([
               },
             ],
           },
-      {
-        type: "link",
-        path: "/troubleshooting",
-        title: "Troubleshooting Guides",
-        isChildSidebar: true,
-        children: troubleshootingSidebar,
-      },
+          ...troubleshootingSidebar,
         ],
       },
       {
@@ -174,12 +141,19 @@ export const sidebar = sidebarAttachHrefCommonOptions([
             path: "/admin-widget-injection-zones",
             title: "Admin Widget Injection Zones",
           },
+          {
+            type: "sidebar",
+            sidebar_id: "admin-components",
+            title: "Admin Components",
+            children: [
               {
                 type: "link",
                 path: "/admin-components",
-        title: "Admin Components",
-        isChildSidebar: true,
-        children: [
+                title: "Overview",
+              },
+              {
+                type: "separator",
+              },
               {
                 type: "category",
                 title: "Layouts",
@@ -215,4 +189,6 @@ export const sidebar = sidebarAttachHrefCommonOptions([
         title: "References",
         children: referencesSidebar,
       },
-])
+    ],
+  },
+]

www/apps/resources/sidebars/api-key.mjs

@@ -1,9 +1,9 @@
-/** @type {import('types').RawSidebarItem[]} */
+/** @type {import('types').Sidebar.SidebarItem[]} */
 export const apiKeySidebar = [
   {
-    type: "category",
+    type: "sidebar",
+    sidebar_id: "api-key",
     title: "API Key Module",
-    isChildSidebar: true,
     children: [
       {
         type: "link",
@@ -131,12 +131,19 @@ export const apiKeySidebar = [
             title: "Admin Widget Zones",
           },
           {
-            type: "link",
-            path: "/references/api-key",
+            type: "sidebar",
+            sidebar_id: "api-key-service-reference",
             title: "Main Service Reference",
-            isChildSidebar: true,
             childSidebarTitle: "API Key Module's Main Service Reference",
             children: [
+              {
+                type: "link",
+                path: "/references/api-key",
+                title: "Reference Overview",
+              },
+              {
+                type: "separator",
+              },
               {
                 type: "category",
                 title: "Methods",
@@ -147,12 +154,19 @@ export const apiKeySidebar = [
             ],
           },
           {
-            type: "link",
-            path: "/references/api-key/models",
+            type: "sidebar",
+            sidebar_id: "api-key-models-reference",
             title: "Data Models Reference",
-            isChildSidebar: true,
             childSidebarTitle: "API Key Module Data Models Reference",
             children: [
+              {
+                type: "link",
+                path: "/references/api-key/models",
+                title: "Reference Overview",
+              },
+              {
+                type: "separator",
+              },
               {
                 type: "category",
                 title: "Data Models",

www/apps/resources/sidebars/architectural-modules.mjs

@@ -1,5 +1,18 @@
-/** @type {import('types').RawSidebarItem[]} */
+/** @type {import('types').Sidebar.SidebarItem[]} */
 export const architecturalModulesSidebar = [
+  {
+    type: "sidebar",
+    sidebar_id: "architectural-modules",
+    title: "Architectural Modules",
+    children: [
+      {
+        type: "link",
+        path: "/architectural-modules",
+        title: "Overview",
+      },
+      {
+        type: "separator",
+      },
       {
         type: "category",
         title: "Cache Modules",
@@ -159,4 +172,6 @@ export const architecturalModulesSidebar = [
           },
         ],
       },
+    ],
+  },
 ]

www/apps/resources/sidebars/auth.mjs

@@ -1,9 +1,9 @@
-/** @type {import('types').RawSidebarItem[]} */
+/** @type {import('types').Sidebar.SidebarItem[]} */
 export const authSidebar = [
   {
-    type: "category",
+    type: "sidebar",
+    sidebar_id: "auth",
     title: "Auth Module",
-    isChildSidebar: true,
     children: [
       {
         type: "link",
@@ -173,12 +173,19 @@ export const authSidebar = [
             title: "Admin Widget Zones",
           },
           {
-            type: "link",
-            path: "/references/auth",
+            type: "sidebar",
+            sidebar_id: "auth-service-reference",
             title: "Main Service Reference",
-            isChildSidebar: true,
             childSidebarTitle: "Auth Module's Main Service Reference",
             children: [
+              {
+                type: "link",
+                path: "/references/auth",
+                title: "Reference Overview",
+              },
+              {
+                type: "separator",
+              },
               {
                 type: "category",
                 title: "Methods",
@@ -188,12 +195,19 @@ export const authSidebar = [
             ],
           },
           {
-            type: "link",
-            path: "/references/auth/models",
+            type: "sidebar",
+            sidebar_id: "auth-models-reference",
             title: "Data Models Reference",
-            isChildSidebar: true,
             childSidebarTitle: "Auth Module Data Models Reference",
             children: [
+              {
+                type: "link",
+                path: "/references/auth/models",
+                title: "Reference Overview",
+              },
+              {
+                type: "separator",
+              },
               {
                 type: "category",
                 title: "Data Models",

www/apps/resources/sidebars/cart.mjs

@@ -1,9 +1,9 @@
-/** @type {import('types').RawSidebarItem[]} */
+/** @type {import('types').Sidebar.SidebarItem[]} */
 export const cartSidebar = [
   {
-    type: "category",
+    type: "sidebar",
+    sidebar_id: "cart",
     title: "Cart Module",
-    isChildSidebar: true,
     children: [
       {
         type: "link",
@@ -148,12 +148,19 @@ export const cartSidebar = [
             title: "Events Reference",
           },
           {
-            type: "link",
-            path: "/references/cart",
+            type: "sidebar",
+            sidebar_id: "cart-service-reference",
             title: "Main Service Reference",
-            isChildSidebar: true,
             childSidebarTitle: "Cart Module's Main Service Reference",
             children: [
+              {
+                type: "link",
+                path: "/references/cart",
+                title: "Reference Overview",
+              },
+              {
+                type: "separator",
+              },
               {
                 type: "category",
                 title: "Methods",
@@ -163,12 +170,19 @@ export const cartSidebar = [
             ],
           },
           {
-            type: "link",
-            path: "/references/cart/models",
+            type: "sidebar",
+            sidebar_id: "cart-models-reference",
             title: "Data Models Reference",
-            isChildSidebar: true,
             childSidebarTitle: "Cart Module Data Models Reference",
             children: [
+              {
+                type: "link",
+                path: "/references/cart/models",
+                title: "Reference Overview",
+              },
+              {
+                type: "separator",
+              },
               {
                 type: "category",
                 title: "Data Models",

www/apps/resources/sidebars/currency.mjs

@@ -1,9 +1,9 @@
-/** @type {import('types').RawSidebarItem[]} */
+/** @type {import('types').Sidebar.SidebarItem[]} */
 export const currencySidebar = [
   {
-    type: "category",
+    type: "sidebar",
+    sidebar_id: "currency",
     title: "Currency Module",
-    isChildSidebar: true,
     children: [
       {
         type: "link",
@@ -99,12 +99,19 @@ export const currencySidebar = [
             ],
           },
           {
-            type: "link",
-            path: "/references/currency",
+            type: "sidebar",
+            sidebar_id: "currency-service-reference",
             title: "Main Service Reference",
-            isChildSidebar: true,
             childSidebarTitle: "Currency Module's Main Service Reference",
             children: [
+              {
+                type: "link",
+                path: "/references/currency",
+                title: "Reference Overview",
+              },
+              {
+                type: "separator",
+              },
               {
                 type: "category",
                 title: "Methods",
@@ -114,12 +121,19 @@ export const currencySidebar = [
             ],
           },
           {
-            type: "link",
-            path: "/references/currency/models",
+            type: "sidebar",
+            sidebar_id: "currency-models-reference",
             title: "Data Models Reference",
-            isChildSidebar: true,
             childSidebarTitle: "Currency Module Data Models Reference",
             children: [
+              {
+                type: "link",
+                path: "/references/currency/models",
+                title: "Reference Overview",
+              },
+              {
+                type: "separator",
+              },
               {
                 type: "category",
                 title: "Data Models",

www/apps/resources/sidebars/customer.mjs

@@ -1,9 +1,9 @@
-/** @type {import('types').RawSidebarItem[]} */
+/** @type {import('types').Sidebar.SidebarItem[]} */
 export const customerSidebar = [
   {
-    type: "category",
+    type: "sidebar",
+    sidebar_id: "customer",
     title: "Customer Module",
-    isChildSidebar: true,
     children: [
       {
         type: "link",
@@ -143,12 +143,19 @@ export const customerSidebar = [
             title: "Admin Widget Zones",
           },
           {
-            type: "link",
-            path: "/references/customer",
+            type: "sidebar",
+            sidebar_id: "customer-service-reference",
             title: "Main Service Reference",
-            isChildSidebar: true,
             childSidebarTitle: "Customer Module's Main Service Reference",
             children: [
+              {
+                type: "link",
+                path: "/references/customer",
+                title: "Reference Overview",
+              },
+              {
+                type: "separator",
+              },
               {
                 type: "category",
                 title: "Methods",
@@ -158,12 +165,19 @@ export const customerSidebar = [
             ],
           },
           {
-            type: "link",
-            path: "/references/customer/models",
+            type: "sidebar",
+            sidebar_id: "customer-models-reference",
             title: "Data Models Reference",
-            isChildSidebar: true,
             childSidebarTitle: "Customer Module Data Models Reference",
             children: [
+              {
+                type: "link",
+                path: "/references/customer/models",
+                title: "Reference Overview",
+              },
+              {
+                type: "separator",
+              },
               {
                 type: "category",
                 title: "Data Models",

www/apps/resources/sidebars/examples.mjs

@@ -1,13 +1,12 @@
-/** @type {import('types').RawSidebarItem[]} */
+/** @type {import('types').Sidebar.SidebarItem[]} */
 export const examplesSidebar = [
   {
-    type: "link",
-    path: "/examples",
+    type: "sidebar",
+    sidebar_id: "examples",
     title: "Examples",
-    isChildSidebar: true,
     children: [
       {
-        type: "ref",
+        type: "link",
         path: "/examples",
         title: "Example Snippets",
       },
@@ -32,13 +31,6 @@ export const examplesSidebar = [
         autogenerate_tags: "example+server",
         autogenerate_as_ref: true,
         sort_sidebar: "alphabetize",
-        children: [
-          {
-            type: "link",
-            title: "Custom Item Price",
-            path: "/examples/guides/custom-item-price",
-          },
-        ],
       },
       {
         type: "category",

www/apps/resources/sidebars/fulfillment.mjs

@@ -1,9 +1,9 @@
-/** @type {import('types').RawSidebarItem[]} */
+/** @type {import('types').Sidebar.SidebarItem[]} */
 export const fulfillmentSidebar = [
   {
-    type: "category",
+    type: "sidebar",
+    sidebar_id: "fulfillment",
     title: "Fulfillment Module",
-    isChildSidebar: true,
     children: [
       {
         type: "link",
@@ -170,12 +170,19 @@ export const fulfillmentSidebar = [
             title: "Admin Widget Zones",
           },
           {
-            type: "link",
-            path: "/references/fulfillment",
+            type: "sidebar",
+            sidebar_id: "fulfillment-service-reference",
             title: "Main Service Reference",
-            isChildSidebar: true,
             childSidebarTitle: "Fulfillment Module's Main Service Reference",
             children: [
+              {
+                type: "link",
+                path: "/references/fulfillment",
+                title: "Reference Overview",
+              },
+              {
+                type: "separator",
+              },
               {
                 type: "category",
                 title: "Methods",
@@ -185,12 +192,19 @@ export const fulfillmentSidebar = [
             ],
           },
           {
-            type: "link",
-            path: "/references/fulfillment/models",
+            type: "sidebar",
+            sidebar_id: "fulfillment-models-reference",
             title: "Data Models Reference",
-            isChildSidebar: true,
             childSidebarTitle: "Fulfillment Module Data Models Reference",
             children: [
+              {
+                type: "link",
+                path: "/references/fulfillment/models",
+                title: "Reference Overview",
+              },
+              {
+                type: "separator",
+              },
               {
                 type: "category",
                 title: "Data Models",

www/apps/resources/sidebars/integrations.mjs

@@ -1,5 +1,18 @@
-/** @type {import('types').RawSidebarItem[]} */
+/** @type {import('types').Sidebar.SidebarItem[]} */
 export const integrationsSidebar = [
+  {
+    type: "sidebar",
+    sidebar_id: "integrations",
+    title: "Integrations",
+    children: [
+      {
+        type: "link",
+        path: "/integrations",
+        title: "Overview",
+      },
+      {
+        type: "separator",
+      },
       {
         type: "category",
         title: "Auth",
@@ -76,4 +89,6 @@ export const integrationsSidebar = [
           },
         ],
       },
+    ],
+  },
 ]

www/apps/resources/sidebars/inventory.mjs

@@ -1,9 +1,9 @@
-/** @type {import('types').RawSidebarItem[]} */
+/** @type {import('types').Sidebar.SidebarItem[]} */
 export const inventorySidebar = [
   {
-    type: "category",
+    type: "sidebar",
+    sidebar_id: "inventory",
     title: "Inventory Module",
-    isChildSidebar: true,
     children: [
       {
         type: "link",
@@ -143,12 +143,19 @@ export const inventorySidebar = [
             title: "Admin Widget Zones",
           },
           {
-            type: "link",
-            path: "/references/inventory-next",
+            type: "sidebar",
+            sidebar_id: "inventory-service-reference",
             title: "Main Service Reference",
-            isChildSidebar: true,
             childSidebarTitle: "Inventory Module's Main Service Reference",
             children: [
+              {
+                type: "link",
+                path: "/references/inventory-next",
+                title: "Reference Overview",
+              },
+              {
+                type: "separator",
+              },
               {
                 type: "category",
                 title: "Methods",
@@ -158,12 +165,19 @@ export const inventorySidebar = [
             ],
           },
           {
-            type: "link",
-            path: "/references/inventory-next/models",
+            type: "sidebar",
+            sidebar_id: "inventory-models-reference",
             title: "Data Models Reference",
-            isChildSidebar: true,
             childSidebarTitle: "Inventory Module Data Models Reference",
             children: [
+              {
+                type: "link",
+                path: "/references/inventory-next/models",
+                title: "Reference Overview",
+              },
+              {
+                type: "separator",
+              },
               {
                 type: "category",
                 title: "Data Models",

www/apps/resources/sidebars/order-module.mjs

@@ -1,9 +1,9 @@
-/** @type {import('types').RawSidebarItem[]} */
+/** @type {import('types').Sidebar.SidebarItem[]} */
 export const orderSidebar = [
   {
-    type: "category",
+    type: "sidebar",
+    sidebar_id: "order",
     title: "Order Module",
-    isChildSidebar: true,
     children: [
       {
         type: "link",
@@ -181,12 +181,19 @@ export const orderSidebar = [
             title: "Admin Widget Zones",
           },
           {
-            type: "link",
-            path: "/references/order",
+            type: "sidebar",
+            sidebar_id: "order-service-reference",
             title: "Main Service Reference",
-            isChildSidebar: true,
             childSidebarTitle: "Order Module's Main Service Reference",
             children: [
+              {
+                type: "link",
+                path: "/references/order",
+                title: "Reference Overview",
+              },
+              {
+                type: "separator",
+              },
               {
                 type: "category",
                 title: "Methods",
@@ -196,12 +203,19 @@ export const orderSidebar = [
             ],
           },
           {
-            type: "link",
-            path: "/references/order/models",
+            type: "sidebar",
+            sidebar_id: "order-models-reference",
             title: "Data Models Reference",
-            isChildSidebar: true,
             childSidebarTitle: "Order Module Data Models Reference",
             children: [
+              {
+                type: "link",
+                path: "/references/order/models",
+                title: "Reference Overview",
+              },
+              {
+                type: "separator",
+              },
               {
                 type: "category",
                 title: "Data Models",

www/apps/resources/sidebars/payment.mjs

@@ -1,9 +1,9 @@
-/** @type {import('types').RawSidebarItem[]} */
+/** @type {import('types').Sidebar.SidebarItem[]} */
 export const paymentSidebar = [
   {
-    type: "category",
+    type: "sidebar",
+    sidebar_id: "payment",
     title: "Payment Module",
-    isChildSidebar: true,
     children: [
       {
         type: "link",
@@ -185,12 +185,19 @@ export const paymentSidebar = [
             title: "Events Reference",
           },
           {
-            type: "link",
-            path: "/references/payment",
+            type: "sidebar",
+            sidebar_id: "payment-service-reference",
             title: "Main Service Reference",
-            isChildSidebar: true,
             childSidebarTitle: "Payment Module's Main Service Reference",
             children: [
+              {
+                type: "link",
+                path: "/references/payment",
+                title: "Reference Overview",
+              },
+              {
+                type: "separator",
+              },
               {
                 type: "category",
                 title: "Methods",
@@ -200,12 +207,19 @@ export const paymentSidebar = [
             ],
           },
           {
-            type: "link",
-            path: "/references/payment/models",
+            type: "sidebar",
+            sidebar_id: "payment-models-reference",
             title: "Data Models Reference",
-            isChildSidebar: true,
             childSidebarTitle: "Payment Module Data Models Reference",
             children: [
+              {
+                type: "link",
+                path: "/references/payment/models",
+                title: "Reference Overview",
+              },
+              {
+                type: "separator",
+              },
               {
                 type: "category",
                 title: "Data Models",

www/apps/resources/sidebars/plugins.mjs

@@ -1,5 +1,10 @@
-/** @type {import('types').RawSidebarItem[]} */
+/** @type {import('types').Sidebar.SidebarItem[]} */
 export const pluginsSidebar = [
+  {
+    type: "sidebar",
+    sidebar_id: "plugins",
+    title: "Plugins",
+    children: [
       {
         type: "link",
         title: "Overview",
@@ -17,4 +22,6 @@ export const pluginsSidebar = [
           },
         ],
       },
+    ],
+  },
 ]

www/apps/resources/sidebars/pricing.mjs

@@ -1,9 +1,9 @@
-/** @type {import('types').RawSidebarItem[]} */
+/** @type {import('types').Sidebar.SidebarItem[]} */
 export const pricingSidebar = [
   {
-    type: "category",
+    type: "sidebar",
+    sidebar_id: "pricing",
     title: "Pricing Module",
-    isChildSidebar: true,
     children: [
       {
         type: "link",
@@ -146,12 +146,19 @@ export const pricingSidebar = [
             title: "Admin Widget Zones",
           },
           {
-            type: "link",
-            path: "/references/pricing",
+            type: "sidebar",
+            sidebar_id: "pricing-service-reference",
             title: "Main Service Reference",
-            isChildSidebar: true,
             childSidebarTitle: "Pricing Module's Main Service Reference",
             children: [
+              {
+                type: "link",
+                path: "/references/pricing",
+                title: "Reference Overview",
+              },
+              {
+                type: "separator",
+              },
               {
                 type: "category",
                 title: "Methods",
@@ -161,12 +168,19 @@ export const pricingSidebar = [
             ],
           },
           {
-            type: "link",
-            path: "/references/pricing/models",
+            type: "sidebar",
+            sidebar_id: "pricing-models-reference",
             title: "Data Models Reference",
-            isChildSidebar: true,
             childSidebarTitle: "Pricing Module Data Models Reference",
             children: [
+              {
+                type: "link",
+                path: "/references/pricing/models",
+                title: "Reference Overview",
+              },
+              {
+                type: "separator",
+              },
               {
                 type: "category",
                 title: "Data Models",

www/apps/resources/sidebars/product.mjs

@@ -1,9 +1,9 @@
-/** @type {import('types').RawSidebarItem[]} */
+/** @type {import('types').Sidebar.SidebarItem[]} */
 export const productSidebar = [
   {
-    type: "category",
+    type: "sidebar",
+    sidebar_id: "product",
     title: "Product Module",
-    isChildSidebar: true,
     children: [
       {
         type: "link",
@@ -160,12 +160,19 @@ export const productSidebar = [
             title: "Admin Widget Zones",
           },
           {
-            type: "link",
-            path: "/references/product",
+            type: "sidebar",
+            sidebar_id: "product-service-reference",
             title: "Main Service Reference",
-            isChildSidebar: true,
             childSidebarTitle: "Product Module's Main Service Reference",
             children: [
+              {
+                type: "link",
+                path: "/references/product",
+                title: "Reference Overview",
+              },
+              {
+                type: "separator",
+              },
               {
                 type: "category",
                 title: "Methods",
@@ -175,12 +182,19 @@ export const productSidebar = [
             ],
           },
           {
-            type: "link",
-            path: "/references/product/models",
+            type: "sidebar",
+            sidebar_id: "product-models-reference",
             title: "Data Models Reference",
-            isChildSidebar: true,
             childSidebarTitle: "Product Module Data Models Reference",
             children: [
+              {
+                type: "link",
+                path: "/references/product/models",
+                title: "Reference Overview",
+              },
+              {
+                type: "separator",
+              },
               {
                 type: "category",
                 title: "Data Models",

www/apps/resources/sidebars/promotion.mjs

@@ -1,9 +1,9 @@
-/** @type {import('types').RawSidebarItem[]} */
+/** @type {import('types').Sidebar.SidebarItem[]} */
 export const promotionSidebar = [
   {
-    type: "category",
+    type: "sidebar",
+    sidebar_id: "promotion",
     title: "Promotion Module",
-    isChildSidebar: true,
     children: [
       {
         type: "link",
@@ -153,12 +153,19 @@ export const promotionSidebar = [
             title: "Admin Widget Zones",
           },
           {
-            type: "link",
-            path: "/references/promotion",
+            type: "sidebar",
+            sidebar_id: "promotion-service-reference",
             title: "Main Service Reference",
-            isChildSidebar: true,
             childSidebarTitle: "Promotion Module's Main Service Reference",
             children: [
+              {
+                type: "link",
+                path: "/references/promotion",
+                title: "Reference Overview",
+              },
+              {
+                type: "separator",
+              },
               {
                 type: "category",
                 title: "Methods",
@@ -169,12 +176,19 @@ export const promotionSidebar = [
             ],
           },
           {
-            type: "link",
-            path: "/references/promotion/models",
+            type: "sidebar",
+            sidebar_id: "promotion-models-reference",
             title: "Data Models Reference",
-            isChildSidebar: true,
             childSidebarTitle: "Promotion Module Data Models Reference",
             children: [
+              {
+                type: "link",
+                path: "/references/promotion/models",
+                title: "Reference Overview",
+              },
+              {
+                type: "separator",
+              },
               {
                 type: "category",
                 title: "Data Models",

www/apps/resources/sidebars/recipes.mjs

@@ -1,5 +1,18 @@
-/** @type {import('types').RawSidebarItem[]} */
+/** @type {import('types').Sidebar.SidebarItem[]} */
 export const recipesSidebar = [
+  {
+    type: "sidebar",
+    sidebar_id: "recipes",
+    title: "Recipes",
+    children: [
+      {
+        type: "link",
+        path: "/recipes",
+        title: "Overview",
+      },
+      {
+        type: "separator",
+      },
       {
         type: "link",
         path: "/recipes/marketplace",
@@ -100,4 +113,6 @@ export const recipesSidebar = [
         path: "/recipes/pos",
         title: "POS",
       },
+    ],
+  },
 ]

www/apps/resources/sidebars/references.mjs

@@ -1,12 +1,19 @@
-/** @type {import('types').RawSidebarItem[]} */
+/** @type {import('types').Sidebar.SidebarItem[]} */
 export const referencesSidebar = [
+  {
+    type: "sidebar",
+    sidebar_id: "workflows-sdk-reference",
+    title: "Workflows SDK",
+    childSidebarTitle: "Workflows SDK Reference",
+    children: [
       {
         type: "link",
         path: "/references/workflows",
-    title: "Workflows SDK",
-    childSidebarTitle: "Workflows SDK Reference",
-    isChildSidebar: true,
-    children: [
+        title: "Reference Overview",
+      },
+      {
+        type: "separator",
+      },
       {
         type: "category",
         title: "Functions",
@@ -15,12 +22,19 @@ export const referencesSidebar = [
     ],
   },
   {
-    type: "link",
-    path: "/references/data-model",
+    type: "sidebar",
+    sidebar_id: "dml-reference",
     title: "Data Model Language",
     childSidebarTitle: "Data Model Language Reference",
-    isChildSidebar: true,
     children: [
+      {
+        type: "link",
+        path: "/references/data-model",
+        title: "Reference Overview",
+      },
+      {
+        type: "separator",
+      },
       {
         type: "link",
         path: "/references/data-model/define",
@@ -52,12 +66,19 @@ export const referencesSidebar = [
       },
     ],
   },
+  {
+    type: "sidebar",
+    sidebar_id: "service-factory-reference",
+    title: "Service Factory",
+    children: [
       {
         type: "link",
         path: "/service-factory-reference",
-    title: "Service Factory",
-    isChildSidebar: true,
-    children: [
+        title: "Reference Overview",
+      },
+      {
+        type: "separator",
+      },
       {
         type: "category",
         title: "Methods",
@@ -71,25 +92,44 @@ export const referencesSidebar = [
     ],
   },
   {
-    type: "link",
-    path: "/references/helper-steps",
+    type: "sidebar",
+    sidebar_id: "helper-steps-reference",
     title: "Helper Steps",
-    isChildSidebar: true,
-    autogenerate_path: "/references/helper_steps/functions",
-  },
+    children: [
       {
         type: "link",
+        path: "/references/helper-steps",
+        title: "Reference Overview",
+      },
+      {
+        type: "separator",
+      },
+      {
+        type: "category",
+        title: "Steps",
+        autogenerate_path: "/references/helper_steps/functions",
+      },
+    ],
+  },
+  {
+    type: "sidebar",
+    sidebar_id: "core-flows",
     title: "Core Workflows",
-    path: "/medusa-workflows-reference",
-    isChildSidebar: true,
     custom_autogenerate: "core-flows",
   },
   {
-    type: "link",
+    type: "sidebar",
+    sidebar_id: "test-tools-reference",
     title: "Testing Framework",
-    path: "/test-tools-reference",
-    isChildSidebar: true,
     children: [
+      {
+        type: "link",
+        path: "/test-tools-reference",
+        title: "Reference Overview",
+      },
+      {
+        type: "separator",
+      },
       {
         type: "category",
         title: "Functions",

www/apps/resources/sidebars/region.mjs

@@ -1,9 +1,9 @@
-/** @type {import('types').RawSidebarItem[]} */
+/** @type {import('types').Sidebar.SidebarItem[]} */
 export const regionSidebar = [
   {
-    type: "category",
+    type: "sidebar",
+    sidebar_id: "region",
     title: "Region Module",
-    isChildSidebar: true,
     children: [
       {
         type: "link",
@@ -131,12 +131,19 @@ export const regionSidebar = [
             title: "Admin Widget Zones",
           },
           {
-            type: "link",
-            path: "/references/region",
+            type: "sidebar",
+            sidebar_id: "region-service-reference",
             title: "Main Service Reference",
-            isChildSidebar: true,
             childSidebarTitle: "Region Module's Main Service Reference",
             children: [
+              {
+                type: "link",
+                path: "/references/region",
+                title: "Reference Overview",
+              },
+              {
+                type: "separator",
+              },
               {
                 type: "category",
                 title: "Methods",
@@ -146,12 +153,19 @@ export const regionSidebar = [
             ],
           },
           {
-            type: "link",
-            path: "/references/region/models",
+            type: "sidebar",
+            sidebar_id: "region-models-reference",
             title: "Data Models Reference",
-            isChildSidebar: true,
             childSidebarTitle: "Region Module Data Models Reference",
             children: [
+              {
+                type: "link",
+                path: "/references/region/models",
+                title: "Reference Overview",
+              },
+              {
+                type: "separator",
+              },
               {
                 type: "category",
                 title: "Data Models",

www/apps/resources/sidebars/sales-channel.mjs

@@ -1,9 +1,9 @@
-/** @type {import('types').RawSidebarItem[]} */
+/** @type {import('types').Sidebar.SidebarItem[]} */
 export const salesChannelSidebar = [
   {
-    type: "category",
+    type: "sidebar",
+    sidebar_id: "sales-channel",
     title: "Sales Channel Module",
-    isChildSidebar: true,
     children: [
       {
         type: "link",
@@ -138,12 +138,16 @@ export const salesChannelSidebar = [
             title: "Admin Widget Zones",
           },
           {
-            type: "link",
-            path: "/references/sales-channel",
+            type: "sidebar",
+            sidebar_id: "sales-channel-service-reference",
             title: "Main Service Reference",
-            isChildSidebar: true,
             childSidebarTitle: "Sales Channel Module's Main Service Reference",
             children: [
+              {
+                type: "link",
+                path: "/references/sales-channel",
+                title: "Reference Overview",
+              },
               {
                 type: "category",
                 title: "Methods",
@@ -153,12 +157,19 @@ export const salesChannelSidebar = [
             ],
           },
           {
-            type: "link",
-            path: "/references/sales-channel/models",
+            type: "sidebar",
+            sidebar_id: "sales-channel-models-reference",
             title: "Data Models Reference",
-            isChildSidebar: true,
             childSidebarTitle: "Sales Channel Module Data Models Reference",
             children: [
+              {
+                type: "link",
+                path: "/references/sales-channel/models",
+                title: "Reference Overview",
+              },
+              {
+                type: "separator",
+              },
               {
                 type: "category",
                 title: "Data Models",

www/apps/resources/sidebars/sdk-tools.mjs

@@ -1,4 +1,4 @@
-/** @type {import('types').RawSidebarItem[]} */
+/** @type {import('types').Sidebar.SidebarItem[]} */
 export const sdkToolsSidebar = [
   {
     type: "link",
@@ -6,10 +6,9 @@ export const sdkToolsSidebar = [
     title: "create-medusa-app",
   },
   {
-    type: "link",
-    path: "/medusa-cli",
+    type: "sidebar",
+    sidebar_id: "medusa-cli",
     title: "Medusa CLI",
-    isChildSidebar: true,
     childSidebarTitle: "Medusa CLI Reference",
     children: [
       {
@@ -28,12 +27,19 @@ export const sdkToolsSidebar = [
     ],
   },
   {
-    type: "link",
-    path: "/js-sdk",
+    type: "sidebar",
+    sidebar_id: "js-sdk",
     title: "JS SDK",
-    isChildSidebar: true,
     childSidebarTitle: "JS SDK Reference",
     children: [
+      {
+        type: "link",
+        path: "/js-sdk",
+        title: "Overview",
+      },
+      {
+        type: "separator",
+      },
       {
         type: "category",
         title: "Auth",
@@ -55,10 +61,9 @@ export const sdkToolsSidebar = [
     ],
   },
   {
-    type: "link",
-    path: "/nextjs-starter",
+    type: "sidebar",
+    sidebar_id: "nextjs-starter",
     title: "Next.js Starter Storefront",
-    isChildSidebar: true,
     children: [
       {
         type: "link",

www/apps/resources/sidebars/stock-location.mjs

@@ -1,9 +1,9 @@
-/** @type {import('types').RawSidebarItem[]} */
+/** @type {import('types').Sidebar.SidebarItem[]} */
 export const stockLocationSidebar = [
   {
-    type: "category",
+    type: "sidebar",
+    sidebar_id: "stock-location",
     title: "Stock Location Module",
-    isChildSidebar: true,
     children: [
       {
         type: "link",
@@ -133,12 +133,19 @@ export const stockLocationSidebar = [
             title: "Admin Widget Zones",
           },
           {
-            type: "link",
-            path: "/references/stock-location-next",
+            type: "sidebar",
+            sidebar_id: "stock-location-service-reference",
             title: "Main Service Reference",
-            isChildSidebar: true,
             childSidebarTitle: "Stock Location Module's Main Service Reference",
             children: [
+              {
+                type: "link",
+                path: "/references/stock-location-next",
+                title: "Reference Overview",
+              },
+              {
+                type: "separator",
+              },
               {
                 type: "category",
                 title: "Methods",
@@ -148,12 +155,19 @@ export const stockLocationSidebar = [
             ],
           },
           {
-            type: "link",
-            path: "/references/stock-location-next/models",
+            type: "sidebar",
+            sidebar_id: "stock-location-models-reference",
             title: "Data Models Reference",
-            isChildSidebar: true,
             childSidebarTitle: "Stock Location Module Data Models Reference",
             children: [
+              {
+                type: "link",
+                path: "/references/stock-location-next/models",
+                title: "Reference Overview",
+              },
+              {
+                type: "separator",
+              },
               {
                 type: "category",
                 title: "Data Models",

www/apps/resources/sidebars/store.mjs

@@ -1,9 +1,9 @@
-/** @type {import('types').RawSidebarItem[]} */
+/** @type {import('types').Sidebar.SidebarItem[]} */
 export const storeSidebar = [
   {
-    type: "category",
+    type: "sidebar",
+    sidebar_id: "store",
     title: "Store Module",
-    isChildSidebar: true,
     children: [
       {
         type: "link",
@@ -126,12 +126,19 @@ export const storeSidebar = [
             title: "Admin Widget Zones",
           },
           {
-            type: "link",
-            path: "/references/store",
+            type: "sidebar",
+            sidebar_id: "store-service-reference",
             title: "Main Service Reference",
-            isChildSidebar: true,
             childSidebarTitle: "Store Module's Main Service Reference",
             children: [
+              {
+                type: "link",
+                path: "/references/store",
+                title: "Reference Overview",
+              },
+              {
+                type: "separator",
+              },
               {
                 type: "category",
                 title: "Methods",
@@ -141,12 +148,19 @@ export const storeSidebar = [
             ],
           },
           {
-            type: "link",
-            path: "/references/store/models",
+            type: "sidebar",
+            sidebar_id: "store-models-reference",
             title: "Data Models Reference",
-            isChildSidebar: true,
             childSidebarTitle: "Store Module Data Models Reference",
             children: [
+              {
+                type: "link",
+                path: "/references/store/models",
+                title: "Reference Overview",
+              },
+              {
+                type: "separator",
+              },
               {
                 type: "category",
                 title: "Data Models",

www/apps/resources/sidebars/storefront.mjs

@@ -1,5 +1,18 @@
-/** @type {import('types').RawSidebarItem[]} */
+/** @type {import('types').Sidebar.SidebarItem[]} */
 export const storefrontGuidesSidebar = [
+  {
+    type: "sidebar",
+    sidebar_id: "storefront-development",
+    title: "Storefront Development",
+    children: [
+      {
+        type: "link",
+        path: "/storefront-development",
+        title: "Overview",
+      },
+      {
+        type: "separator",
+      },
       {
         type: "category",
         title: "General",
@@ -257,4 +270,6 @@ export const storefrontGuidesSidebar = [
           },
         ],
       },
+    ],
+  },
 ]

www/apps/resources/sidebars/tax.mjs

@@ -1,9 +1,9 @@
-/** @type {import('types').RawSidebarItem[]} */
+/** @type {import('types').Sidebar.SidebarItem[]} */
 export const taxSidebar = [
   {
-    type: "category",
+    type: "sidebar",
+    sidebar_id: "tax",
     title: "Tax Module",
-    isChildSidebar: true,
     children: [
       {
         type: "link",
@@ -148,12 +148,19 @@ export const taxSidebar = [
             title: "Admin Widget Zones",
           },
           {
-            type: "link",
-            path: "/references/tax",
+            type: "sidebar",
+            sidebar_id: "tax-service-reference",
             title: "Main Service Reference",
-            isChildSidebar: true,
             childSidebarTitle: "Tax Module's Main Service Reference",
             children: [
+              {
+                type: "link",
+                path: "/references/tax",
+                title: "Reference Overview",
+              },
+              {
+                type: "separator",
+              },
               {
                 type: "category",
                 title: "Methods",
@@ -162,12 +169,19 @@ export const taxSidebar = [
             ],
           },
           {
-            type: "link",
-            path: "/references/tax/models",
+            type: "sidebar",
+            sidebar_id: "tax-models-reference",
             title: "Data Models Reference",
-            isChildSidebar: true,
             childSidebarTitle: "Tax Module Data Models Reference",
             children: [
+              {
+                type: "link",
+                path: "/references/tax/models",
+                title: "Reference Overview",
+              },
+              {
+                type: "separator",
+              },
               {
                 type: "category",
                 title: "Data Models",

www/apps/resources/sidebars/troubleshooting.mjs

@@ -1,5 +1,18 @@
-/** @type {import('types').RawSidebarItem[]} */
+/** @type {import('types').Sidebar.SidebarItem[]} */
 export const troubleshootingSidebar = [
+  {
+    type: "sidebar",
+    sidebar_id: "troubleshooting",
+    title: "Troubleshooting",
+    children: [
+      {
+        type: "link",
+        path: "/troubleshooting",
+        title: "Overview",
+      },
+      {
+        type: "separator",
+      },
       {
         type: "category",
         title: "Installation",
@@ -97,4 +110,6 @@ export const troubleshootingSidebar = [
           },
         ],
       },
+    ],
+  },
 ]

www/apps/resources/sidebars/user.mjs

@@ -1,9 +1,9 @@
-/** @type {import('types').RawSidebarItem[]} */
+/** @type {import('types').Sidebar.SidebarItem[]} */
 export const userSidebar = [
   {
-    type: "category",
+    type: "sidebar",
+    sidebar_id: "user",
     title: "User Module",
-    isChildSidebar: true,
     children: [
       {
         type: "link",
@@ -131,12 +131,19 @@ export const userSidebar = [
             title: "Admin Widget Zones",
           },
           {
-            type: "link",
-            path: "/references/user",
+            type: "sidebar",
+            sidebar_id: "user-service-reference",
             title: "Main Service Reference",
-            isChildSidebar: true,
             childSidebarTitle: "User Module's Main Service Reference",
             children: [
+              {
+                type: "link",
+                path: "/references/user",
+                title: "Reference Overview",
+              },
+              {
+                type: "separator",
+              },
               {
                 type: "category",
                 title: "Methods",
@@ -146,12 +153,19 @@ export const userSidebar = [
             ],
           },
           {
-            type: "link",
-            path: "/references/user/models",
+            type: "sidebar",
+            sidebar_id: "user-models-reference",
             title: "Data Models Reference",
-            isChildSidebar: true,
             childSidebarTitle: "User Module Data Models Reference",
             children: [
+              {
+                type: "link",
+                path: "/references/user/models",
+                title: "Reference Overview",
+              },
+              {
+                type: "separator",
+              },
               {
                 type: "category",
                 title: "Data Models",

www/apps/resources/types/index.d.ts

@@ -1,6 +0,0 @@
-import { SidebarItemType as UiSidebarItemType } from "docs-ui"
-
-export declare type SidebarItemType = UiSidebarItemType & {
-  autogenerate_path?: string
-  children?: SidebarItemType[]
-}

www/apps/resources/utils/sidebar-attach-common-options.mjs

@@ -1,24 +0,0 @@
-/** @type {Partial<import("../types").RawSidebarItem>} */
-const commonOptions = {
-  loaded: true,
-  isPathHref: true,
-}
-
-/**
- *
- * @param {import("types").RawSidebarItem[]} sidebar
- * @returns {import("types").RawSidebarItem[]}
- */
-export function sidebarAttachHrefCommonOptions(sidebar) {
-  return sidebar.map((item) => {
-    if (item.type === "separator") {
-      return item
-    }
-
-    return {
-      ...commonOptions,
-      ...item,
-      children: sidebarAttachHrefCommonOptions(item.children || []),
-    }
-  })
-}

www/apps/ui/src/app/assets/sitemap.ts

@@ -1,8 +1,8 @@
 import { MetadataRoute } from "next"
 
-import { docsConfig } from "@/config/docs"
+import { sidebars } from "@/config/sidebar"
 import { absoluteUrl } from "@/lib/absolute-url"
-import { SidebarItem } from "types"
+import { Sidebar } from "types"
 
 export default function sitemap(): MetadataRoute.Sitemap {
   const now = new Date()
@@ -12,7 +12,7 @@ export default function sitemap(): MetadataRoute.Sitemap {
     lastModified?: string | Date
   }> = []
 
-  function pushItems(newItems: SidebarItem[]) {
+  function pushItems(newItems: Sidebar.SidebarItem[]) {
     newItems.forEach((item) => {
       if (item.type !== "link") {
         return
@@ -29,7 +29,7 @@ export default function sitemap(): MetadataRoute.Sitemap {
     })
   }
 
-  pushItems(docsConfig.sidebar.default)
+  sidebars.forEach((sidebar) => pushItems(sidebar.items))
 
   return items
 }

www/apps/ui/src/app/layout.tsx

@@ -60,14 +60,7 @@ export default function RootLayout({
       htmlClassName={clsx(inter.variable, robotoMono.variable)}
       gaId={process.env.NEXT_PUBLIC_GA_ID}
     >
-      <TightLayout
-        sidebarProps={{
-          expandItems: true,
-        }}
-        ProvidersComponent={Providers}
-      >
-        {children}
-      </TightLayout>
+      <TightLayout ProvidersComponent={Providers}>{children}</TightLayout>
     </BareboneLayout>
   )
 }

www/apps/ui/src/config/colors.ts

@@ -1,226 +1,182 @@
 export const colors = {
   dark: {
-    "--fg-on-color": "rgba(255, 255, 255, 1)",
-    "--border-danger": "rgba(190, 18, 60, 1)",
-    "--border-interactive": "rgba(96, 165, 250, 1)",
-    "--fg-interactive-hover": "rgba(59, 130, 246, 1)",
-    "--fg-error": "rgba(251, 113, 133, 1)",
-    "--bg-interactive": "rgba(96, 165, 250, 1)",
-    "--border-error": "rgba(244, 63, 94, 1)",
-    "--button-danger": "rgba(159, 18, 57, 1)",
-    "--button-danger-gradient-from": "rgba(255, 255, 255, 1)",
-    "--button-danger-gradient-to": "rgba(255, 255, 255, 0)",
-    "--fg-interactive": "rgba(96, 165, 250, 1)",
-    "--tag-red-border": "rgba(136, 19, 55, 1)",
-    "--tag-red-bg": "rgba(76, 5, 25, 1)",
-    "--tag-blue-text": "rgba(96, 165, 250, 1)",
-    "--tag-orange-text": "rgba(251, 191, 36, 1)",
-    "--tag-green-text": "rgba(52, 211, 153, 1)",
-    "--tag-orange-border": "rgba(120, 53, 15, 1)",
-    "--tag-green-border": "rgba(6, 78, 59, 1)",
-    "--tag-red-text": "rgba(251, 113, 133, 1)",
-    "--tag-green-bg-hover": "rgba(6, 78, 59, 1)",
-    "--tag-purple-bg-hover": "rgba(76, 29, 149, 1)",
-    "--tag-red-bg-hover": "rgba(136, 19, 55, 1)",
-    "--border-transparent": "rgba(255, 255, 255, 0)",
-    "--tag-orange-icon": "rgba(245, 158, 11, 1)",
-    "--tag-purple-bg": "rgba(46, 16, 100, 1)",
-    "--tag-blue-bg": "rgba(23, 37, 84, 1)",
-    "--tag-green-bg": "rgba(2, 44, 34, 1)",
-    "--tag-blue-border": "rgba(30, 58, 138, 1)",
-    "--tag-purple-border": "rgba(76, 29, 149, 1)",
-    "--tag-blue-bg-hover": "rgba(30, 42, 138, 1)",
-    "--tag-orange-bg": "rgba(69, 26, 3, 1)",
-    "--tag-orange-bg-hover": "rgba(120, 53, 15, 1)",
-    "--tag-blue-icon": "rgba(59, 130, 246, 1)",
-    "--tag-red-icon": "rgba(244, 63, 94, 1)",
-    "--tag-purple-icon": "rgba(139, 92, 246, 1)",
-    "--tag-purple-text": "rgba(167, 139, 250, 1)",
-    "--tag-green-icon": "rgba(16, 185, 129, 1)",
     "--button-danger-pressed": "rgba(225, 29, 72, 1)",
-    "--button-danger-pressed-gradient-from": "rgba(255, 255, 255, 1)",
-    "--button-danger-pressed-gradient-to": "rgba(255, 255, 255, 0)",
-    "--button-danger-hover": "rgba(190, 18, 60, 1)",
-    "--button-danger-hover-gradient-from": "rgba(255, 255, 255, 1)",
-    "--button-danger-hover-gradient-to": "rgba(255, 255, 255, 0)",
-    "--button-transparent": "rgba(0, 0, 0, 0.01)",
-    "--code-bg-base": "rgba(9, 9, 11, 1)",
-    "--button-neutral": "rgba(39, 39, 42, 1)",
-    "--button-neutral-gradient-from": "rgba(255, 255, 255, 1)",
-    "--button-neutral-gradient-to": "rgba(255, 255, 255, 0)",
-    "--button-transparent-hover": "rgba(39, 39, 42, 1)",
-    "--code-fg-subtle": "rgba(161, 161, 170, 1)",
-    "--tag-neutral-bg-hover": "rgba(63, 63, 70, 1)",
-    "--contrast-border-base": "rgba(82, 82, 91, 1)",
-    "--button-neutral-pressed": "rgba(82, 82, 91, 1)",
-    "--button-neutral-pressed-gradient-from": "rgba(255, 255, 255, 1)",
-    "--button-neutral-pressed-gradient-to": "rgba(255, 255, 255, 0)",
-    "--tag-neutral-bg": "rgba(39, 39, 42, 1)",
+    "--bg-base-pressed": "rgba(63, 63, 70, 1)",
+    "--bg-component-hover": "rgba(255, 255, 255, 0.1)",
+    "--border-interactive": "rgba(96, 165, 250, 1)",
+    "--button-neutral": "rgba(255, 255, 255, 0.04)",
+    "--tag-orange-border": "rgba(124, 45, 18, 1)",
+    "--tag-blue-text": "rgba(147, 197, 253, 1)",
     "--bg-highlight": "rgba(23, 37, 84, 1)",
-    "--border-base": "rgba(255, 255, 255, 0.1)",
-    "--code-fg-base": "rgba(250, 250, 250, 1)",
     "--tag-neutral-icon": "rgba(113, 113, 122, 1)",
     "--bg-switch-off-hover": "rgba(82, 82, 91, 1)",
-    "--bg-base": "rgba(24, 24, 27, 1)",
+    "--fg-on-color": "rgba(255, 255, 255, 1)",
     "--button-inverted-pressed": "rgba(161, 161, 170, 1)",
-    "--button-inverted-pressed-gradient-from": "rgba(255, 255, 255, 1)",
-    "--button-inverted-pressed-gradient-to": "rgba(255, 255, 255, 0)",
-    "--button-neutral-hover": "rgba(63, 63, 70, 1)",
-    "--button-neutral-hover-gradient-from": "rgba(255, 255, 255, 1)",
-    "--button-neutral-hover-gradient-to": "rgba(255, 255, 255, 0)",
+    "--fg-interactive-hover": "rgba(147, 197, 253, 1)",
+    "--fg-error": "rgba(251, 113, 133, 1)",
     "--bg-switch-off": "rgba(63, 63, 70, 1)",
-    "--border-strong": "rgba(255, 255, 255, 0.15)",
+    "--border-strong": "rgba(255, 255, 255, 0.16)",
+    "--border-error": "rgba(251, 113, 133, 1)",
     "--fg-subtle": "rgba(161, 161, 170, 1)",
     "--bg-highlight-hover": "rgba(30, 58, 138, 1)",
     "--button-inverted": "rgba(82, 82, 91, 1)",
-    "--button-inverted-gradient-from": "rgba(255, 255, 255, 1)",
-    "--button-inverted-gradient-to": "rgba(255, 255, 255, 0)",
-    "--fg-base": "rgba(250, 250, 250, 1)",
-    "--code-border": "rgba(39, 39, 42, 1)",
-    "--contrast-bg-subtle": "rgba(39, 39, 42, 1)",
-    "--contrast-bg-base-hover": "rgba(82, 82, 91, 1)",
-    "--bg-base-hover": "rgba(39, 39, 42, 1)",
-    "--bg-subtle-hover": "rgba(24, 24, 27, 1)",
-    "--fg-disabled": "rgba(63, 63, 70, 1)",
-    "--bg-subtle": "rgba(9, 9, 11, 1)",
-    "--tag-neutral-border": "rgba(63, 63, 70, 1)",
-    "--bg-subtle-pressed": "rgba(39, 39, 42, 1)",
-    "--tag-neutral-text": "rgba(161, 161, 170, 1)",
-    "--fg-muted": "rgba(82, 82, 91, 1)",
-    "--bg-overlay": "rgba(9, 9, 11, 0.7)",
+    "--tag-orange-text": "rgba(253, 186, 116, 1)",
+    "--fg-base": "rgba(244, 244, 245, 1)",
+    "--fg-disabled": "rgba(82, 82, 91, 1)",
+    "--button-danger": "rgba(159, 18, 57, 1)",
+    "--tag-neutral-border": "rgba(255, 255, 255, 0.06)",
+    "--tag-blue-border": "rgba(30, 58, 138, 1)",
+    "--tag-neutral-text": "rgba(212, 212, 216, 1)",
+    "--tag-purple-border": "rgba(91, 33, 182, 1)",
+    "--tag-green-text": "rgba(52, 211, 153, 1)",
     "--button-inverted-hover": "rgba(113, 113, 122, 1)",
-    "--button-inverted-hover-gradient-from": "rgba(255, 255, 255, 1)",
-    "--button-inverted-hover-gradient-to": "rgba(255, 255, 255, 0)",
-    "--fg-on-inverted": "rgba(9, 9, 11, 1)",
-    "--code-bg-subtle": "rgba(24, 24, 27, 1)",
+    "--bg-component-pressed": "rgba(255, 255, 255, 0.16)",
+    "--contrast-border-bot": "rgba(255, 255, 255, 0.08)",
+    "--tag-blue-icon": "rgba(96, 165, 250, 1)",
+    "--bg-field": "rgba(255, 255, 255, 0.04)",
+    "--tag-neutral-bg": "rgba(255, 255, 255, 0.08)",
+    "--tag-green-border": "rgba(6, 78, 59, 1)",
+    "--tag-red-icon": "rgba(251, 113, 133, 1)",
+    "--tag-red-text": "rgba(253, 164, 175, 1)",
+    "--tag-purple-icon": "rgba(167, 139, 250, 1)",
+    "--bg-interactive": "rgba(96, 165, 250, 1)",
+    "--bg-field-hover": "rgba(255, 255, 255, 0.08)",
+    "--border-transparent": "rgba(255, 255, 255, 0)",
+    "--tag-orange-icon": "rgba(251, 146, 60, 1)",
+    "--tag-purple-bg": "rgba(46, 16, 101, 1)",
+    "--bg-base-hover": "rgba(39, 39, 42, 1)",
+    "--tag-blue-bg": "rgba(23, 37, 84, 1)",
+    "--tag-green-bg": "rgba(2, 44, 34, 1)",
+    "--tag-purple-text": "rgba(196, 181, 253, 1)",
+    "--tag-red-border": "rgba(136, 19, 55, 1)",
+    "--border-danger": "rgba(190, 18, 60, 1)",
+    "--tag-green-icon": "rgba(16, 185, 129, 1)",
+    "--tag-red-bg": "rgba(76, 5, 25, 1)",
+    "--fg-interactive": "rgba(96, 165, 250, 1)",
+    "--tag-orange-bg": "rgba(67, 20, 7, 1)",
+    "--button-danger-hover": "rgba(190, 18, 60, 1)",
     "--bg-component": "rgba(39, 39, 42, 1)",
-    "--border-loud": "rgba(250, 250, 250, 1)",
-    "--bg-base-pressed": "rgba(63, 63, 70, 1)",
     "--bg-disabled": "rgba(39, 39, 42, 1)",
-    "--contrast-bg-highlight": "rgba(82, 82, 91, 1)",
-    "--button-transparent-pressed": "rgba(63, 63, 70, 1)",
-    "--code-fg-muted": "rgba(82, 82, 91, 1)",
-    "--contrast-fg-secondary": "rgba(161, 161, 170, 1)",
-    "--contrast-bg-base-pressed": "rgba(113, 113, 122, 1)",
-    "--contrast-fg-primary": "rgba(250, 250, 250, 1)",
-    "--contrast-bg-base": "rgba(63, 63, 70, 1)",
-    "--bg-component-pressed": "rgba(82, 82, 91, 1)",
-    "--bg-component-hover": "rgba(63, 63, 70, 1)",
-    "--bg-field": "rgba(39, 39, 42, 1)",
-    "--bg-field-component": "rgba(24, 24, 27, 1)",
-    "--bg-field-component-hover": "rgba(24, 24, 27, 1)",
-    "--bg-field-hover": "rgba(39, 39, 42, 1)",
+    "--button-transparent": "rgba(255, 255, 255, 0)",
+    "--border-menu-bot": "rgba(255, 255, 255, 0.08)",
+    "--tag-purple-bg-hover": "rgba(91, 33, 182, 1)",
+    "--tag-orange-bg-hover": "rgba(124, 45, 18, 1)",
+    "--tag-blue-bg-hover": "rgba(30, 58, 138, 1)",
+    "--tag-red-bg-hover": "rgba(136, 19, 55, 1)",
+    "--tag-green-bg-hover": "rgba(6, 78, 59, 1)",
+    "--border-menu-top": "rgba(33, 33, 36, 1)",
+    "--bg-base": "rgba(33, 33, 36, 1)",
+    "--contrast-border-top": "rgba(33, 33, 36, 1)",
+    "--bg-field-component": "rgba(33, 33, 36, 1)",
+    "--bg-subtle-hover": "rgba(33, 33, 36, 1)",
+    "--bg-subtle": "rgba(24, 24, 27, 1)",
+    "--fg-on-inverted": "rgba(24, 24, 27, 1)",
+    "--bg-overlay": "rgba(24, 24, 27, 0.72)",
+    "--button-transparent-hover": "rgba(255, 255, 255, 0.08)",
+    "--contrast-fg-secondary": "rgba(255, 255, 255, 0.56)",
+    "--contrast-border-base": "rgba(255, 255, 255, 0.16)",
+    "--contrast-bg-base-pressed": "rgba(82, 82, 91, 1)",
+    "--button-neutral-pressed": "rgba(255, 255, 255, 0.12)",
+    "--border-base": "rgba(255, 255, 255, 0.08)",
+    "--contrast-fg-primary": "rgba(255, 255, 255, 0.88)",
+    "--button-neutral-hover": "rgba(255, 255, 255, 0.08)",
+    "--contrast-bg-base": "rgba(39, 39, 42, 1)",
+    "--tag-neutral-bg-hover": "rgba(255, 255, 255, 0.12)",
+    "--contrast-bg-subtle": "rgba(255, 255, 255, 0.04)",
+    "--contrast-bg-base-hover": "rgba(63, 63, 70, 1)",
+    "--bg-field-component-hover": "rgba(39, 39, 42, 1)",
+    "--bg-subtle-pressed": "rgba(39, 39, 42, 1)",
+    "--button-transparent-pressed": "rgba(255, 255, 255, 0.12)",
+    "--fg-muted": "rgba(113, 113, 122, 1)",
   },
   light: {
-    "--tag-green-bg": "rgba(209, 250, 229, 1)",
-    "--border-interactive": "rgba(59, 130, 246, 1)",
-    "--bg-highlight": "rgba(239, 246, 255, 1)",
-    "--tag-red-bg": "rgba(255, 228, 230, 1)",
-    "--tag-orange-bg": "rgba(254, 244, 199, 1)",
-    "--bg-base": "rgba(255, 255, 255, 1)",
-    "--tag-green-icon": "rgba(5, 150, 105, 1)",
-    "--tag-purple-bg-hover": "rgba(221, 214, 254, 1)",
-    "--tag-blue-border": "rgba(191, 219, 254, 1)",
-    "--tag-orange-icon": "rgba(217, 119, 6, 1)",
-    "--tag-purple-bg": "rgba(237, 233, 254, 1)",
-    "--tag-purple-text": "rgba(109, 40, 217, 1)",
-    "--tag-blue-bg": "rgba(219, 234, 254, 1)",
-    "--tag-blue-icon": "rgba(37, 99, 235, 1)",
-    "--border-error": "rgba(225, 29, 72, 1)",
-    "--fg-on-inverted": "rgba(255, 255, 255, 1)",
-    "--fg-on-color": "rgba(255, 255, 255, 1)",
-    "--fg-interactive-hover": "rgba(37, 99, 235, 1)",
-    "--fg-interactive": "rgba(59, 130, 246, 1)",
-    "--fg-error": "rgba(225, 29, 72, 1)",
-    "--border-danger": "rgba(190, 18, 60, 1)",
-    "--fg-muted": "rgba(161, 161, 170, 1)",
-    "--bg-subtle-pressed": "rgba(228, 228, 231, 1)",
-    "--tag-green-bg-hover": "rgba(167, 243, 208, 1)",
-    "--tag-blue-bg-hover": "rgba(191, 219, 254, 1)",
-    "--tag-red-icon": "rgba(225, 29, 72, 1)",
-    "--tag-red-bg-hover": "rgba(254, 205, 211, 1)",
-    "--tag-red-text": "rgba(190, 18, 60, 1)",
-    "--tag-purple-icon": "rgba(124, 58, 237, 1)",
-    "--tag-blue-text": "rgba(29, 78, 216, 1)",
-    "--tag-orange-bg-hover": "rgba(253, 230, 138, 1)",
-    "--tag-purple-border": "rgba(221, 214, 254, 1)",
-    "--tag-orange-text": "rgba(180, 83, 9, 1)",
-    "--tag-orange-border": "rgba(253, 230, 138, 1)",
-    "--tag-red-border": "rgba(254, 205, 211, 1)",
-    "--tag-green-border": "rgba(167, 243, 208, 1)",
-    "--tag-green-text": "rgba(4, 120, 87, 1)",
-    "--button-danger": "rgba(225, 29, 72, 1)",
-    "--button-danger-gradient-from": "rgba(255, 255, 255, 1)",
-    "--button-danger-gradient-to": "rgba(255, 255, 255, 0)",
-    "--button-danger-pressed": "rgba(159, 18, 57, 1)",
-    "--button-danger-pressed-gradient-from": "rgba(255, 255, 255, 1)",
-    "--button-danger-pressed-gradient-to": "rgba(255, 255, 255, 0)",
-    "--button-danger-hover": "rgba(190, 18, 60, 1)",
-    "--button-danger-hover-gradient-from": "rgba(255, 255, 255, 1)",
-    "--button-danger-hover-gradient-to": "rgba(255, 255, 255, 0)",
-    "--bg-interactive": "rgba(59, 130, 246, 1)",
-    "--bg-highlight-hover": "rgba(219, 234, 254, 1)",
-    "--button-transparent": "rgba(255, 255, 255, 0.01)",
-    "--bg-overlay": "rgba(9, 9, 11, 0.4)",
     "--tag-neutral-border": "rgba(228, 228, 231, 1)",
-    "--border-loud": "rgba(9, 9, 11, 1)",
-    "--contrast-fg-primary": "rgba(250, 250, 250, 1)",
+    "--tag-neutral-icon": "rgba(161, 161, 170, 1)",
+    "--bg-switch-off-hover": "rgba(212, 212, 216, 1)",
+    "--border-menu-bot": "rgba(255, 255, 255, 1)",
+    "--border-menu-top": "rgba(228, 228, 231, 1)",
+    "--bg-subtle-hover": "rgba(244, 244, 245, 1)",
+    "--contrast-fg-primary": "rgba(255, 255, 255, 0.88)",
     "--bg-switch-off": "rgba(228, 228, 231, 1)",
     "--contrast-bg-base-pressed": "rgba(63, 63, 70, 1)",
+    "--bg-field-component-hover": "rgba(250, 250, 250, 1)",
     "--bg-base-pressed": "rgba(228, 228, 231, 1)",
     "--tag-neutral-text": "rgba(82, 82, 91, 1)",
-    "--button-transparent-hover": "rgba(244, 244, 245, 1)",
+    "--tag-red-text": "rgba(159, 18, 57, 1)",
     "--contrast-bg-base": "rgba(24, 24, 27, 1)",
-    "--fg-disabled": "rgba(212, 212, 216, 1)",
-    "--bg-field": "rgba(250, 250, 250, 1)",
     "--border-strong": "rgba(212, 212, 216, 1)",
-    "--bg-field-hover": "rgba(244, 244, 245, 1)",
-    "--contrast-border-base": "rgba(82, 82, 91, 1)",
-    "--fg-base": "rgba(9, 9, 11, 1)",
-    "--contrast-bg-subtle": "rgba(39, 39, 42, 1)",
-    "--contrast-fg-secondary": "rgba(161, 161, 170, 1)",
-    "--code-fg-subtle": "rgba(161, 161, 170, 1)",
-    "--tag-neutral-bg": "rgba(244, 244, 245, 1)",
-    "--button-transparent-pressed": "rgba(228, 228, 231, 1)",
-    "--tag-neutral-bg-hover": "rgba(228, 228, 231, 1)",
-    "--code-fg-muted": "rgba(113, 113, 122, 1)",
-    "--contrast-bg-highlight": "rgba(63, 63, 70, 1)",
-    "--tag-neutral-icon": "rgba(113, 113, 122, 1)",
-    "--border-base": "rgba(228, 228, 231, 1)",
-    "--code-bg-base": "rgba(24, 24, 27, 1)",
-    "--button-neutral": "rgba(255, 255, 255, 1)",
-    "--button-neutral-gradient-from": "rgba(9, 9, 11, 0)",
-    "--button-neutral-gradient-to": "rgba(9, 9, 11, 1)",
-    "--code-bg-subtle": "rgba(39, 39, 42, 1)",
-    "--button-neutral-hover": "rgba(244, 244, 245, 1)",
-    "--button-neutral-hover-gradient-from": "rgba(9, 9, 11, 0)",
-    "--button-neutral-hover-gradient-to": "rgba(9, 9, 11, 1)",
-    "--contrast-bg-base-hover": "rgba(39, 39, 42, 1)",
-    "--bg-subtle": "rgba(250, 250, 250, 1)",
-    "--bg-switch-off-hover": "rgba(212, 212, 216, 1)",
-    "--code-fg-base": "rgba(250, 250, 250, 1)",
-    "--bg-disabled": "rgba(244, 244, 245, 1)",
-    "--code-border": "rgba(63, 63, 70, 1)",
-    "--fg-subtle": "rgba(82, 82, 91, 1)",
-    "--bg-subtle-hover": "rgba(244, 244, 245, 1)",
-    "--button-neutral-pressed": "rgba(228, 228, 231, 1)",
-    "--button-neutral-pressed-gradient-from": "rgba(9, 9, 11, 0)",
-    "--button-neutral-pressed-gradient-to": "rgba(9, 9, 11, 1)",
-    "--border-transparent": "rgba(9, 9, 11, 0)",
-    "--button-inverted": "rgba(9, 9, 11, 1)",
-    "--button-inverted-gradient-from": "rgba(255, 255, 255, 1)",
-    "--button-inverted-gradient-to": "rgba(255, 255, 255, 0)",
-    "--button-inverted-pressed": "rgba(39, 39, 42, 1)",
-    "--button-inverted-pressed-gradient-from": "rgba(255, 255, 255, 1)",
-    "--button-inverted-pressed-gradient-to": "rgba(255, 255, 255, 0)",
-    "--button-inverted-hover": "rgba(24, 24, 27, 1)",
-    "--button-inverted-hover-gradient-from": "rgba(255, 255, 255, 1)",
-    "--button-inverted-hover-gradient-to": "rgba(255, 255, 255, 0)",
-    "--bg-component-hover": "rgba(244, 244, 245, 1)",
-    "--bg-field-component": "rgba(255, 255, 255, 1)",
-    "--bg-field-component-hover": "rgba(250, 250, 250, 1)",
-    "--bg-component-pressed": "rgba(228, 228, 231, 1)",
-    "--bg-component": "rgba(250, 250, 250, 1)",
+    "--contrast-border-base": "rgba(255, 255, 255, 0.15)",
+    "--bg-field": "rgba(250, 250, 250, 1)",
+    "--tag-blue-text": "rgba(30, 64, 175, 1)",
+    "--button-inverted-pressed": "rgba(82, 82, 91, 1)",
+    "--border-interactive": "rgba(59, 130, 246, 1)",
     "--bg-base-hover": "rgba(244, 244, 245, 1)",
+    "--contrast-bg-subtle": "rgba(39, 39, 42, 1)",
+    "--bg-highlight": "rgba(239, 246, 255, 1)",
+    "--contrast-fg-secondary": "rgba(255, 255, 255, 0.56)",
+    "--tag-red-bg": "rgba(255, 228, 230, 1)",
+    "--button-transparent": "rgba(255, 255, 255, 0)",
+    "--button-danger-pressed": "rgba(159, 18, 57, 1)",
+    "--fg-on-color": "rgba(255, 255, 255, 1)",
+    "--button-inverted-hover": "rgba(63, 63, 70, 1)",
+    "--bg-field-component": "rgba(255, 255, 255, 1)",
+    "--tag-orange-text": "rgba(154, 52, 18, 1)",
+    "--tag-green-icon": "rgba(16, 185, 129, 1)",
+    "--border-base": "rgba(228, 228, 231, 1)",
+    "--bg-base": "rgba(255, 255, 255, 1)",
+    "--tag-orange-border": "rgba(254, 215, 170, 1)",
+    "--tag-red-border": "rgba(254, 205, 211, 1)",
+    "--tag-green-border": "rgba(167, 243, 208, 1)",
+    "--tag-green-text": "rgba(6, 95, 70, 1)",
+    "--button-neutral": "rgba(255, 255, 255, 1)",
+    "--tag-blue-border": "rgba(191, 219, 254, 1)",
+    "--fg-interactive-hover": "rgba(37, 99, 235, 1)",
+    "--tag-orange-icon": "rgba(249, 115, 22, 1)",
+    "--button-neutral-hover": "rgba(244, 244, 245, 1)",
+    "--fg-interactive": "rgba(59, 130, 246, 1)",
+    "--bg-component-pressed": "rgba(228, 228, 231, 1)",
+    "--tag-purple-bg": "rgba(237, 233, 254, 1)",
+    "--contrast-bg-base-hover": "rgba(39, 39, 42, 1)",
+    "--bg-component": "rgba(250, 250, 250, 1)",
+    "--bg-subtle": "rgba(250, 250, 250, 1)",
+    "--tag-purple-text": "rgba(91, 33, 182, 1)",
+    "--contrast-border-bot": "rgba(255, 255, 255, 0.1)",
+    "--button-inverted": "rgba(39, 39, 42, 1)",
+    "--tag-red-icon": "rgba(244, 63, 94, 1)",
+    "--button-transparent-hover": "rgba(244, 244, 245, 1)",
+    "--button-neutral-pressed": "rgba(228, 228, 231, 1)",
+    "--tag-purple-icon": "rgba(167, 139, 250, 1)",
+    "--bg-field-hover": "rgba(244, 244, 245, 1)",
+    "--fg-on-inverted": "rgba(255, 255, 255, 1)",
+    "--bg-interactive": "rgba(59, 130, 246, 1)",
+    "--border-danger": "rgba(190, 18, 60, 1)",
+    "--button-transparent-pressed": "rgba(228, 228, 231, 1)",
+    "--tag-purple-border": "rgba(221, 214, 254, 1)",
+    "--bg-highlight-hover": "rgba(219, 234, 254, 1)",
+    "--border-error": "rgba(225, 29, 72, 1)",
+    "--button-danger": "rgba(225, 29, 72, 1)",
+    "--tag-blue-bg": "rgba(219, 234, 254, 1)",
+    "--border-transparent": "rgba(255, 255, 255, 0)",
+    "--button-danger-hover": "rgba(190, 18, 60, 1)",
+    "--bg-subtle-pressed": "rgba(228, 228, 231, 1)",
+    "--fg-error": "rgba(225, 29, 72, 1)",
+    "--bg-component-hover": "rgba(244, 244, 245, 1)",
+    "--bg-disabled": "rgba(244, 244, 245, 1)",
+    "--tag-blue-icon": "rgba(96, 165, 250, 1)",
+    "--fg-subtle": "rgba(82, 82, 91, 1)",
+    "--tag-orange-bg-hover": "rgba(254, 215, 170, 1)",
+    "--tag-green-bg-hover": "rgba(167, 243, 208, 1)",
+    "--tag-red-bg-hover": "rgba(254, 205, 211, 1)",
+    "--tag-purple-bg-hover": "rgba(221, 214, 254, 1)",
+    "--tag-neutral-bg-hover": "rgba(228, 228, 231, 1)",
+    "--tag-blue-bg-hover": "rgba(191, 219, 254, 1)",
+    "--tag-green-bg": "rgba(209, 250, 229, 1)",
+    "--tag-neutral-bg": "rgba(244, 244, 245, 1)",
+    "--tag-orange-bg": "rgba(255, 237, 213, 1)",
+    "--fg-base": "rgba(24, 24, 27, 1)",
+    "--contrast-border-top": "rgba(24, 24, 27, 1)",
+    "--bg-overlay": "rgba(24, 24, 27, 0.4)",
+    "--fg-disabled": "rgba(161, 161, 170, 1)",
+    "--fg-muted": "rgba(113, 113, 122, 1)",
   },
 }

www/apps/ui/src/config/sidebar.tsx

@@ -1,12 +1,10 @@
-import { SidebarSectionItems } from "types"
+import { Sidebar } from "types"
 
-type DocsConfig = {
-  sidebar: SidebarSectionItems
-}
-
-export const docsConfig: DocsConfig = {
-  sidebar: {
-    default: [
+export const sidebars: Sidebar.Sidebar[] = [
+  {
+    sidebar_id: "ui",
+    title: "Medusa UI",
+    items: [
       {
         type: "link",
         title: "Introduction",
@@ -364,6 +362,5 @@ export const docsConfig: DocsConfig = {
         ],
       },
     ],
-    mobile: [],
   },
-}
+]

www/apps/ui/src/config/site.ts

@@ -1,5 +1,6 @@
 import { globalConfig } from "docs-ui"
 import { DocsConfig } from "types"
+import { sidebars } from "./sidebar"
 
 type SiteConfig = {
   name: string
@@ -16,17 +17,18 @@ export const siteConfig: SiteConfig = {
   basePath: process.env.NEXT_PUBLIC_BASE_PATH,
   url: `${baseUrl}/${process.env.NEXT_PUBLIC_BASE_PATH}`,
   description: "Primitives for building Medusa applications.",
-  // sidebar is defined in docs.tsx
-  sidebar: {
-    default: [],
-    mobile: [],
-  },
+  sidebars,
   project: {
     title: "Medusa UI",
     key: "ui",
   },
   breadcrumbOptions: {
-    showCategories: true,
+    startItems: [
+      {
+        title: "Documentation",
+        link: baseUrl,
+      },
+    ],
   },
   logo: `${process.env.NEXT_PUBLIC_BASE_PATH}/images/logo.png`,
   version: {

www/apps/ui/src/providers/sidebar.tsx

@@ -2,7 +2,7 @@ import {
   SidebarProvider as UiSidebarProvider,
   useScrollController,
 } from "docs-ui"
-import { docsConfig } from "@/config/docs"
+import { sidebars } from "@/config/sidebar"
 
 type SidebarProviderProps = {
   children?: React.ReactNode
@@ -13,11 +13,8 @@ const SidebarProvider = ({ children }: SidebarProviderProps) => {
 
   return (
     <UiSidebarProvider
-      initialItems={docsConfig.sidebar}
-      shouldHandlePathChange={true}
+      sidebars={sidebars}
       scrollableElement={scrollableElement}
-      disableActiveTransition={true}
-      projectName="ui"
     >
       {children}
     </UiSidebarProvider>

www/apps/ui/src/types/nav.ts

@@ -1,8 +0,0 @@
-export interface SidebarNavItem {
-  title: string
-  href?: string
-  disabled?: boolean
-  external?: boolean
-  label?: string
-  items?: SidebarNavItem[]
-}

www/apps/user-guide/app/layout.tsx

@@ -64,13 +64,7 @@ export default function RootLayout({
       htmlClassName={clsx(inter.variable, robotoMono.variable)}
       gaId={process.env.NEXT_PUBLIC_GA_ID}
     >
-      <TightLayout
-        sidebarProps={{
-          expandItems: true,
-        }}
-        ProvidersComponent={Providers}
-        footerComponent={<Footer />}
-      >
+      <TightLayout ProvidersComponent={Providers} footerComponent={<Footer />}>
         {children}
         <Feedback className="my-2" />
         <EditButton />

www/apps/user-guide/config/index.ts

@@ -1,5 +1,5 @@
-import { DocsConfig, SidebarItem } from "types"
-import { generatedSidebar as sidebar } from "@/generated/sidebar.mjs"
+import { DocsConfig, Sidebar } from "types"
+import { generatedSidebars } from "@/generated/sidebar.mjs"
 import { globalConfig } from "docs-ui"
 
 const baseUrl = process.env.NEXT_PUBLIC_BASE_URL || "http://localhost:3000"
@@ -9,16 +9,18 @@ export const config: DocsConfig = {
   titleSuffix: "Medusa Admin User Guide",
   baseUrl,
   basePath: process.env.NEXT_PUBLIC_BASE_PATH,
-  sidebar: {
-    default: sidebar as SidebarItem[],
-    mobile: [],
-  },
+  sidebars: generatedSidebars as Sidebar.Sidebar[],
   project: {
     title: "User Guide",
     key: "user-guide",
   },
-  breadcrumbOptions: {
-    showCategories: true,
-  },
   logo: `${process.env.NEXT_PUBLIC_BASE_PATH}/images/logo.png`,
+  breadcrumbOptions: {
+    startItems: [
+      {
+        title: "Documentation",
+        link: baseUrl,
+      },
+    ],
+  },
 }

www/apps/user-guide/generated/sidebar.mjs

@@ -1,4 +1,8 @@
-export const generatedSidebar = [
+export const generatedSidebars = [
+  {
+    "sidebar_id": "user-guide",
+    "title": "User Guide",
+    "items": [
       {
         "loaded": true,
         "isPathHref": true,
@@ -507,3 +511,5 @@ export const generatedSidebar = [
         ]
       }
     ]
+  }
+]

www/apps/user-guide/providers/sidebar.tsx

@@ -14,13 +14,8 @@ const SidebarProvider = ({ children }: SidebarProviderProps) => {
 
   return (
     <UiSidebarProvider
-      shouldHandlePathChange={true}
-      shouldHandleHashChange={false}
       scrollableElement={scrollableElement}
-      initialItems={config.sidebar}
-      staticSidebarItems={true}
-      disableActiveTransition={true}
-      projectName="user-guide"
+      sidebars={config.sidebars}
     >
       {children}
     </UiSidebarProvider>

www/apps/user-guide/sidebar.mjs

@@ -1,9 +1,9 @@
-import { sidebarAttachHrefCommonOptions } from "build-scripts"
-
-// TODO check the order of items based on the Medusa Admin's sidebar
-
-/** @type {import('types').RawSidebarItemType[]} */
-export const sidebar = sidebarAttachHrefCommonOptions([
+/** @type {import('types').Sidebar.RawSidebar[]} */
+export const sidebar = [
+  {
+    sidebar_id: "user-guide",
+    title: "User Guide",
+    items: [
       {
         type: "link",
         path: "/",
@@ -317,4 +317,6 @@ export const sidebar = sidebarAttachHrefCommonOptions([
           },
         ],
       },
-])
+    ],
+  },
+]

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

@@ -1,13 +1,14 @@
-import type { RawSidebarItem, SidebarItem } from "types"
 import { existsSync, mkdirSync, readdirSync, statSync } from "fs"
 import path from "path"
-import { getSidebarItemLink, sidebarAttachHrefCommonOptions } from "./index.js"
+import { getSidebarItemLink, sidebarAttachCommonOptions } 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"
 import { sortSidebarItems } from "./utils/sidebar-sorting.js"
+import { Sidebar } from "types"
+import { validateSidebarUniqueIds } from "./utils/validate-sidebar-unique-ids.js"
 
-export type ItemsToAdd = SidebarItem & {
+export type ItemsToAdd = Sidebar.SidebarItem & {
   sidebar_position?: number
 }
 
@@ -52,9 +53,7 @@ async function getAutogeneratedSidebarItems(
           loaded: true,
         })
       } else {
-        items.push(
-          ...(sidebarAttachHrefCommonOptions(newItems) as ItemsToAdd[])
-        )
+        items.push(...newItems)
       }
       continue
     }
@@ -96,7 +95,7 @@ async function getAutogeneratedSidebarItems(
 async function getAutogeneratedTagSidebarItems(
   tags: string,
   type: "link" | "ref",
-  existingChildren?: RawSidebarItem[]
+  existingChildren?: Sidebar.RawSidebarItem[]
 ): Promise<ItemsToAdd[]> {
   const items: ItemsToAdd[] = []
 
@@ -105,13 +104,15 @@ async function getAutogeneratedTagSidebarItems(
   items.push(
     ...parsedTags
       .filter((tagItem) => {
-        return existingChildren?.every((existingItem) => {
+        return existingChildren
+          ? existingChildren.every((existingItem) => {
               if (existingItem.type !== "link" && existingItem.type !== "ref") {
                 return true
               }
 
               return existingItem.path !== tagItem.path
             })
+          : true
       })
       .map(
         (tagItem) =>
@@ -122,10 +123,12 @@ async function getAutogeneratedTagSidebarItems(
       )
   )
 
-  return sidebarAttachHrefCommonOptions([...(existingChildren || []), ...items])
+  return sidebarAttachCommonOptions([...(existingChildren || []), ...items])
 }
 
-async function checkItem(item: RawSidebarItem): Promise<RawSidebarItem> {
+async function checkItem(
+  item: Sidebar.RawSidebarItem
+): Promise<Sidebar.RawSidebarItem> {
   if (!item.type) {
     throw new Error(
       `ERROR: The following item doesn't have a type: ${JSON.stringify(
@@ -138,14 +141,26 @@ async function checkItem(item: RawSidebarItem): Promise<RawSidebarItem> {
   if (item.type === "separator") {
     return item
   }
+  if (item.type === "sidebar" && !item.sidebar_id) {
+    throw new Error(
+      `ERROR: The following sidebar item doesn't have a sidebar_id: ${JSON.stringify(
+        item,
+        undefined,
+        2
+      )}`
+    )
+  }
   if (item.autogenerate_path) {
-    item.children = (
-      await getAutogeneratedSidebarItems(item.autogenerate_path)
-    ).map((child) => {
+    item.children = [
+      ...(item.children || []),
+      ...(await getAutogeneratedSidebarItems(item.autogenerate_path)).map(
+        (child) => {
           delete child.sidebar_position
 
           return child
-    })
+        }
+      ),
+    ]
   } else if (item.autogenerate_tags) {
     item.children = await getAutogeneratedTagSidebarItems(
       item.autogenerate_tags,
@@ -156,13 +171,16 @@ async function checkItem(item: RawSidebarItem): Promise<RawSidebarItem> {
     item.custom_autogenerate &&
     Object.hasOwn(customGenerators, item.custom_autogenerate)
   ) {
-    item.children = await customGenerators[item.custom_autogenerate]()
+    item.children = [
+      ...(item.children || []),
+      ...(await customGenerators[item.custom_autogenerate]()),
+    ]
   } else if (item.children) {
     item.children = await checkItems(item.children)
   }
 
   item.children = sortSidebarItems({
-    items: item.children as RawSidebarItem[],
+    items: item.children as Sidebar.RawSidebarItem[],
     type: item.sort_sidebar,
   })
 
@@ -170,10 +188,10 @@ async function checkItem(item: RawSidebarItem): Promise<RawSidebarItem> {
 }
 
 async function checkItems(
-  items: RawSidebarItem[],
+  items: Sidebar.RawSidebarItem[],
   options?: GenerateSidebarOptions
-): Promise<RawSidebarItem[]> {
-  const updatedItems = (
+): Promise<Sidebar.RawSidebarItem[]> {
+  let updatedItems = (
     await Promise.all(items.map(async (item) => await checkItem(item)))
   ).filter((item) => {
     if (item.type !== "category" && item.type !== "sub-category") {
@@ -184,20 +202,29 @@ async function checkItems(
   })
 
   if (options?.addNumbering) {
-    return numberSidebarItems(updatedItems)
+    updatedItems = numberSidebarItems(updatedItems)
   }
 
-  return updatedItems
+  return sidebarAttachCommonOptions(updatedItems)
 }
 
 export async function generateSidebar(
-  sidebar: RawSidebarItem[],
+  sidebars: Sidebar.RawSidebar[],
   options?: GenerateSidebarOptions
 ): Promise<void> {
   const path = await import("path")
   const { writeFileSync } = await import("fs")
 
-  const normalizedSidebar = await checkItems(sidebar, options)
+  const normalizedSidebars: Sidebar.RawSidebar[] = []
+
+  validateSidebarUniqueIds(sidebars)
+
+  for (const sidebarItem of sidebars) {
+    normalizedSidebars.push({
+      ...sidebarItem,
+      items: await checkItems(sidebarItem.items, options),
+    })
+  }
 
   const generatedDirPath = path.resolve("generated")
 
@@ -208,8 +235,8 @@ export async function generateSidebar(
   // write normalized sidebar
   writeFileSync(
     path.resolve(generatedDirPath, "sidebar.mjs"),
-    `export const generatedSidebar = ${JSON.stringify(
-      normalizedSidebar,
+    `export const generatedSidebars = ${JSON.stringify(
+      normalizedSidebars,
       null,
       2
     )}`,

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)
+  }
+}

www/packages/docs-ui/src/components/Breadcrumbs/index.tsx

@@ -3,94 +3,53 @@
 import React, { useMemo } from "react"
 import clsx from "clsx"
 import Link from "next/link"
-import { SidebarItemLink } from "types"
-import {
-  CurrentItemsState,
-  isSidebarItemLink,
-  useSidebar,
-  useSiteConfig,
-} from "../../providers"
+import { useSidebar, useSiteConfig } from "../../providers"
 import { Button } from "../Button"
 import { TriangleRightMini } from "@medusajs/icons"
+import { Sidebar } from "types"
+
+type BreadcrumbItems = {
+  title: string
+  link: string
+}[]
 
 export const Breadcrumbs = () => {
-  const { currentItems, activeItem: sidebarActiveItem } = useSidebar()
+  const { sidebarHistory, getSidebarFirstLinkChild, getSidebar } = useSidebar()
   const {
-    config: { breadcrumbOptions, project, baseUrl, basePath },
+    config: { breadcrumbOptions },
   } = useSiteConfig()
 
-  const getLinkPath = (item?: SidebarItemLink): string | undefined => {
-    if (!item) {
-      return
-    }
+  const getLinkPath = (item: Sidebar.SidebarItemLink): string => {
     return item.isPathHref ? item.path : `#${item.path}`
   }
 
-  const getBreadcrumbsOfItem = (
-    item: CurrentItemsState
-  ): Map<string, string> => {
-    let tempBreadcrumbItems: Map<string, string> = new Map()
-    if (item.previousSidebar) {
-      tempBreadcrumbItems = getBreadcrumbsOfItem(item.previousSidebar)
-    }
-
-    const parentPath = isSidebarItemLink(item.parentItem)
-      ? getLinkPath(item.parentItem)
-      : (item.parentItem?.type === "category" &&
-            breadcrumbOptions?.showCategories) ||
-          item.parentItem?.type === "sub-category"
-        ? "#"
-        : undefined
-    const firstItemPath = isSidebarItemLink(item.default[0])
-      ? getLinkPath(item.default[0])
-      : (item.default[0].type === "category" &&
-            breadcrumbOptions?.showCategories) ||
-          item.default[0].type === "sub-category"
-        ? "#"
-        : undefined
-
-    const breadcrumbPath = parentPath || firstItemPath || "/"
-
-    tempBreadcrumbItems.set(
-      breadcrumbPath,
-      item.parentItem?.childSidebarTitle ||
-        item.parentItem?.chapterTitle ||
-        item.parentItem?.title ||
-        ""
-    )
-
-    return tempBreadcrumbItems
-  }
-
   const breadcrumbItems = useMemo(() => {
-    const tempBreadcrumbItems: Map<string, string> = new Map()
-    tempBreadcrumbItems.set(`${baseUrl}${basePath}`, project.title)
-
-    if (currentItems) {
-      getBreadcrumbsOfItem(currentItems).forEach((value, key) =>
-        tempBreadcrumbItems.set(key, value)
-      )
+    const items: BreadcrumbItems = []
+    if (breadcrumbOptions?.startItems) {
+      items.push(...breadcrumbOptions.startItems)
     }
 
-    if (sidebarActiveItem) {
-      if (
-        sidebarActiveItem.parentItem &&
-        (sidebarActiveItem.parentItem.type !== "category" ||
-          breadcrumbOptions?.showCategories)
-      ) {
-        tempBreadcrumbItems.set(
-          isSidebarItemLink(sidebarActiveItem.parentItem)
-            ? getLinkPath(sidebarActiveItem.parentItem) || "#"
-            : "#",
-          sidebarActiveItem.parentItem.chapterTitle ||
-            sidebarActiveItem.parentItem.title ||
-            ""
-        )
-      }
+    sidebarHistory.forEach((sidebar_id) => {
+      const sidebar = getSidebar(sidebar_id)
+
+      if (!sidebar) {
+        return
       }
 
-    return tempBreadcrumbItems
-  }, [currentItems, sidebarActiveItem, breadcrumbOptions])
+      const sidebarFirstChild = getSidebarFirstLinkChild(sidebar)
+
+      if (!sidebarFirstChild) {
+        return
+      }
+
+      items.push({
+        title: sidebar.title,
+        link: getLinkPath(sidebarFirstChild),
+      })
+    })
+
+    return items
+  }, [sidebarHistory, breadcrumbOptions])
 
   return (
     <div
@@ -100,7 +59,7 @@ export const Breadcrumbs = () => {
         "mb-docs_1 flex-wrap"
       )}
     >
-      {Array.from(breadcrumbItems).map(([link, title], index) => (
+      {breadcrumbItems.map(({ title, link }, index) => (
         <React.Fragment key={link}>
           {index > 0 && <TriangleRightMini />}
           <Button

www/packages/docs-ui/src/components/Sidebar/Child/index.tsx

@@ -1,17 +1,26 @@
 "use client"
 
-import React from "react"
+import React, { useMemo } from "react"
 import clsx from "clsx"
-import { InteractiveSidebarItem } from "types"
 import { ArrowUturnLeft } from "@medusajs/icons"
-import { useSidebar } from "../../.."
+import { useSidebar } from "../../../providers"
 
-type SidebarTitleProps = {
-  item: InteractiveSidebarItem
+export const SidebarChild = () => {
+  const { goBack, shownSidebar } = useSidebar()
+
+  const title = useMemo(() => {
+    if (!shownSidebar) {
+      return ""
     }
 
-export const SidebarChild = ({ item }: SidebarTitleProps) => {
-  const { goBack } = useSidebar()
+    return "childSidebarTitle" in shownSidebar
+      ? shownSidebar.childSidebarTitle || shownSidebar.title
+      : shownSidebar.title
+  }, [shownSidebar])
+
+  if (!shownSidebar) {
+    return <></>
+  }
 
   return (
     <div className="px-docs_0.75">
@@ -25,9 +34,7 @@ export const SidebarChild = ({ item }: SidebarTitleProps) => {
         tabIndex={-1}
       >
         <ArrowUturnLeft />
-        <span className="truncate flex-1">
-          {item.childSidebarTitle || item.title}
-        </span>
+        <span className="truncate flex-1">{title}</span>
       </div>
     </div>
   )

www/packages/docs-ui/src/components/Sidebar/Item/Category/index.tsx

@@ -3,34 +3,37 @@
 // @refresh reset
 
 import React, { useEffect, useMemo, useState } from "react"
-import { SidebarItemCategory as SidebarItemCategoryType } from "types"
+import { Sidebar } from "types"
 import { Loading, SidebarItem, useSidebar } from "../../../.."
 import clsx from "clsx"
 import { MinusMini, PlusMini } from "@medusajs/icons"
 
-export type SidebarItemCategory = {
-  item: SidebarItemCategoryType
-  expandItems?: boolean
+export type SidebarItemCategoryProps = {
+  item: Sidebar.SidebarItemCategory
 } & React.AllHTMLAttributes<HTMLDivElement>
 
 export const SidebarItemCategory = ({
   item,
-  expandItems = true,
   className,
-}: SidebarItemCategory) => {
+}: SidebarItemCategoryProps) => {
   const [showLoading, setShowLoading] = useState(false)
   const [open, setOpen] = useState(
-    item.initialOpen !== undefined ? item.initialOpen : expandItems
+    item.initialOpen !== undefined ? item.initialOpen : true
   )
   const {
-    isChildrenActive,
+    isItemActive,
     updatePersistedCategoryState,
     getPersistedCategoryState,
-    persistState,
+    persistCategoryState,
   } = useSidebar()
   const itemShowLoading = useMemo(() => {
     return !item.loaded || (item.showLoadingIfEmpty && !item.children?.length)
   }, [item])
+  const isActive = useMemo(() => {
+    return isItemActive({
+      item,
+    })
+  }, [isItemActive, item])
 
   useEffect(() => {
     if (open && itemShowLoading) {
@@ -45,22 +48,20 @@ export const SidebarItemCategory = ({
   }, [itemShowLoading, showLoading])
 
   useEffect(() => {
-    const isActive = isChildrenActive(item)
-
     if (isActive && !open) {
       setOpen(true)
     }
-  }, [isChildrenActive, item.children])
+  }, [isActive, item.children])
 
   useEffect(() => {
-    if (!persistState) {
+    if (!persistCategoryState) {
       return
     }
     const persistedOpen = getPersistedCategoryState(item.title)
-    if (persistedOpen !== undefined) {
+    if (persistedOpen !== undefined && !isActive) {
       setOpen(persistedOpen)
     }
-  }, [persistState])
+  }, [persistCategoryState])
 
   const handleOpen = () => {
     item.onOpen?.()
@@ -90,7 +91,7 @@ export const SidebarItemCategory = ({
             if (!open) {
               handleOpen()
             }
-            if (persistState) {
+            if (persistCategoryState) {
               updatePersistedCategoryState(item.title, !open)
             }
             setOpen((prev) => !prev)
@@ -133,7 +134,7 @@ export const SidebarItemCategory = ({
             <SidebarItem
               item={childItem}
               key={index}
-              expandItems={expandItems}
+              isParentCategoryOpen={open}
             />
           ))}
         </ul>

www/packages/docs-ui/src/components/Sidebar/Item/Link/index.tsx

@@ -2,8 +2,8 @@
 
 // @refresh reset
 
-import React, { useEffect, useMemo, useRef } from "react"
-import { SidebarItemLink as SidebarItemlinkType } from "types"
+import React, { useCallback, useEffect, useMemo, useRef } from "react"
+import { Sidebar } from "types"
 import {
   checkSidebarItemVisibility,
   SidebarItem,
@@ -14,27 +14,36 @@ import clsx from "clsx"
 import Link from "next/link"
 
 export type SidebarItemLinkProps = {
-  item: SidebarItemlinkType
+  item: Sidebar.SidebarItemLink
   nested?: boolean
+  isParentCategoryOpen?: boolean
 } & React.AllHTMLAttributes<HTMLLIElement>
 
 export const SidebarItemLink = ({
   item,
   className,
   nested = false,
+  isParentCategoryOpen,
 }: SidebarItemLinkProps) => {
   const {
-    isLinkActive,
+    isItemActive,
     setMobileSidebarOpen: setSidebarOpen,
     disableActiveTransition,
     sidebarRef,
     sidebarTopHeight,
   } = useSidebar()
   const { isMobile } = useMobile()
-  const active = useMemo(() => isLinkActive(item, true), [isLinkActive, item])
+  const active = useMemo(
+    () =>
+      isItemActive({
+        item,
+        checkLinkChildren: false,
+      }),
+    [isItemActive, item]
+  )
   const ref = useRef<HTMLLIElement>(null)
 
-  const newTopCalculator = useMemo(() => {
+  const getNewTopCalculator = useCallback(() => {
     if (!sidebarRef.current || !ref.current) {
       return 0
     }
@@ -48,10 +57,19 @@ export const SidebarItemLink = ({
       sidebarRef.current.scrollTop -
       10 // remove extra margin just in case
     )
-  }, [sidebarTopHeight, sidebarRef, ref])
+  }, [sidebarTopHeight, sidebarRef.current, ref.current])
 
   useEffect(() => {
-    if (active && ref.current && sidebarRef.current && !isMobile) {
+    if (
+      !active ||
+      !ref.current ||
+      !sidebarRef.current ||
+      isMobile ||
+      !isParentCategoryOpen
+    ) {
+      return
+    }
+
     const isVisible = checkSidebarItemVisibility(
       (ref.current.children.item(0) as HTMLElement) || ref.current,
       !disableActiveTransition
@@ -65,16 +83,17 @@ export const SidebarItemLink = ({
       })
     } else {
       sidebarRef.current.scrollTo({
-          top: newTopCalculator,
+        top: getNewTopCalculator(),
       })
     }
-    }
   }, [
     active,
     sidebarRef.current,
     disableActiveTransition,
     isMobile,
-    newTopCalculator,
+    ref.current,
+    getNewTopCalculator,
+    isParentCategoryOpen,
   ])
 
   useEffect(() => {
@@ -84,11 +103,7 @@ export const SidebarItemLink = ({
   }, [active, isMobile])
 
   const hasChildren = useMemo(() => {
-    return (
-      !item.isChildSidebar &&
-      !item.hideChildren &&
-      (item.children?.length || 0) > 0
-    )
+    return !item.hideChildren && (item.children?.length || 0) > 0
   }, [item.children])
 
   const isTitleOneWord = useMemo(
@@ -147,6 +162,7 @@ export const SidebarItemLink = ({
               item={childItem}
               key={index}
               nested={!item.childrenSameLevel}
+              isParentCategoryOpen={isParentCategoryOpen}
             />
           ))}
         </ul>

www/packages/docs-ui/src/components/Sidebar/Item/Sidebar/index.tsx

@@ -0,0 +1,63 @@
+"use client"
+
+// @refresh reset
+
+import React, { useMemo } from "react"
+import { Sidebar } from "types"
+import { useSidebar } from "../../../.."
+import clsx from "clsx"
+import Link from "next/link"
+
+export type SidebarItemSidebarProps = {
+  item: Sidebar.SidebarItemSidebar
+  nested?: boolean
+} & React.AllHTMLAttributes<HTMLLIElement>
+
+export const SidebarItemSidebar = ({
+  item,
+  className,
+  nested = false,
+}: SidebarItemSidebarProps) => {
+  const { getSidebarFirstLinkChild: getSidebarFirstChild } = useSidebar()
+
+  const isTitleOneWord = useMemo(
+    () => item.title.split(" ").length === 1,
+    [item.title]
+  )
+
+  const firstChild = useMemo(() => getSidebarFirstChild(item), [item])
+
+  return (
+    <li>
+      <span className="block px-docs_0.75">
+        <Link
+          href={
+            firstChild?.isPathHref ? firstChild.path : `#${firstChild?.path}`
+          }
+          className={clsx(
+            "py-docs_0.25 px-docs_0.5",
+            "block w-full rounded-docs_sm",
+            !isTitleOneWord && "break-words",
+            !nested && "text-medusa-fg-subtle",
+            nested && "text-medusa-fg-muted",
+            "hover:bg-medusa-bg-base-hover lg:hover:bg-medusa-bg-subtle-hover",
+            "text-compact-small-plus",
+            "flex justify-between items-center gap-[6px]",
+            className
+          )}
+          {...firstChild?.linkProps}
+        >
+          <span
+            className={clsx(
+              isTitleOneWord && "truncate",
+              nested && "inline-block pl-docs_1.5"
+            )}
+          >
+            {item.title}
+          </span>
+          {item.additionalElms}
+        </Link>
+      </span>
+    </li>
+  )
+}

www/packages/docs-ui/src/components/Sidebar/Item/SubCategory/index.tsx

@@ -2,90 +2,25 @@
 
 // @refresh reset
 
-import React, { useEffect, useMemo, useRef } from "react"
-import { SidebarItemSubCategory as SidebarItemSubCategoryType } from "types"
-import {
-  checkSidebarItemVisibility,
-  SidebarItem,
-  useMobile,
-  useSidebar,
-} from "../../../.."
+import React, { useMemo, useRef } from "react"
+import { Sidebar } from "types"
+import { SidebarItem } from "../../../.."
 import clsx from "clsx"
 
-export type SidebarItemLinkProps = {
-  item: SidebarItemSubCategoryType
+export type SidebarItemSubCategoryProps = {
+  item: Sidebar.SidebarItemSubCategory
   nested?: boolean
+  isParentCategoryOpen?: boolean
 } & React.AllHTMLAttributes<HTMLLIElement>
 
 export const SidebarItemSubCategory = ({
   item,
   className,
   nested = false,
-}: SidebarItemLinkProps) => {
-  const { isLinkActive, disableActiveTransition, sidebarRef } = useSidebar()
-  const { isMobile } = useMobile()
-  const active = useMemo(
-    () => !isMobile && isLinkActive(item, true),
-    [isLinkActive, item, isMobile]
-  )
+  isParentCategoryOpen,
+}: SidebarItemSubCategoryProps) => {
   const ref = useRef<HTMLLIElement>(null)
 
-  /**
-   * Tries to place the item in the center of the sidebar
-   */
-  const newTopCalculator = (): number => {
-    if (!sidebarRef.current || !ref.current) {
-      return 0
-    }
-    const sidebarBoundingRect = sidebarRef.current.getBoundingClientRect()
-    const sidebarHalf = sidebarBoundingRect.height / 2
-    const itemTop = ref.current.offsetTop
-    const itemBottom =
-      itemTop + (ref.current.children.item(0) as HTMLElement)?.clientHeight
-
-    // try deducting half
-    let newTop = itemTop - sidebarHalf
-    let newBottom = newTop + sidebarBoundingRect.height
-    if (newTop <= itemTop && newBottom >= itemBottom) {
-      return newTop
-    }
-
-    // try adding half
-    newTop = itemTop + sidebarHalf
-    newBottom = newTop + sidebarBoundingRect.height
-    if (newTop <= itemTop && newBottom >= itemBottom) {
-      return newTop
-    }
-
-    //return the item's top minus some top margin
-    return itemTop - sidebarBoundingRect.top
-  }
-
-  useEffect(() => {
-    if (
-      active &&
-      ref.current &&
-      sidebarRef.current &&
-      window.innerWidth >= 1025
-    ) {
-      if (
-        !disableActiveTransition &&
-        !checkSidebarItemVisibility(
-          (ref.current.children.item(0) as HTMLElement) || ref.current,
-          !disableActiveTransition
-        )
-      ) {
-        ref.current.scrollIntoView({
-          block: "center",
-        })
-      } else if (disableActiveTransition) {
-        sidebarRef.current.scrollTo({
-          top: newTopCalculator(),
-        })
-      }
-    }
-  }, [active, sidebarRef.current, disableActiveTransition])
-
   const hasChildren = useMemo(() => {
     return !item.hideChildren && (item.children?.length || 0) > 0
   }, [item.children])
@@ -103,15 +38,8 @@ export const SidebarItemSubCategory = ({
             "py-docs_0.25 px-docs_0.5",
             "block w-full",
             !isTitleOneWord && "break-words",
-            active && [
-              "rounded-docs_sm",
-              "shadow-borders-base dark:shadow-borders-base-dark",
-              "text-medusa-fg-base",
-            ],
-            !active && [
             !nested && "text-medusa-fg-subtle",
             nested && "text-medusa-fg-muted",
-            ],
             "text-compact-small-plus",
             className
           )}
@@ -140,6 +68,7 @@ export const SidebarItemSubCategory = ({
               item={childItem}
               key={index}
               nested={!item.childrenSameLevel}
+              isParentCategoryOpen={isParentCategoryOpen}
             />
           ))}
         </ul>

www/packages/docs-ui/src/components/Sidebar/Item/index.tsx

@@ -1,17 +1,18 @@
 "use client"
 
 import React from "react"
-import { SidebarItem as SidebarItemType } from "types"
-import { SidebarItemCategory } from "./Category"
+import { Sidebar } from "types"
 import { SidebarItemLink } from "./Link"
 import { SidebarItemSubCategory } from "./SubCategory"
 import { DottedSeparator } from "../.."
+import { SidebarItemCategory } from "./Category"
+import { SidebarItemSidebar } from "./Sidebar"
 
 export type SidebarItemProps = {
-  item: SidebarItemType
+  item: Sidebar.SidebarItem
   nested?: boolean
-  expandItems?: boolean
   hasNextItems?: boolean
+  isParentCategoryOpen?: boolean
 } & React.AllHTMLAttributes<HTMLElement>
 
 export const SidebarItem = ({
@@ -33,6 +34,8 @@ export const SidebarItem = ({
     case "ref":
     case "external":
       return <SidebarItemLink item={item} {...props} />
+    case "sidebar":
+      return <SidebarItemSidebar item={item} {...props} />
     case "separator":
       return <DottedSeparator />
   }

www/packages/docs-ui/src/components/Sidebar/Top/index.tsx

@@ -2,17 +2,14 @@
 
 import React from "react"
 import { SidebarChild } from "../Child"
-import { InteractiveSidebarItem } from "types"
 import { SidebarTopMobileClose } from "./MobileClose"
-import { DottedSeparator } from "../../.."
+import { DottedSeparator, useSidebar } from "../../.."
 import clsx from "clsx"
 
-export type SidebarTopProps = {
-  parentItem?: InteractiveSidebarItem
-}
+export const SidebarTop = React.forwardRef<HTMLDivElement>(
+  function SidebarTop(props, ref) {
+    const { sidebarHistory } = useSidebar()
 
-export const SidebarTop = React.forwardRef<HTMLDivElement, SidebarTopProps>(
-  function SidebarTop({ parentItem }, ref) {
     return (
       <div
         className={clsx(
@@ -23,9 +20,9 @@ export const SidebarTop = React.forwardRef<HTMLDivElement, SidebarTopProps>(
       >
         <SidebarTopMobileClose />
         <div>
-          {parentItem && (
+          {sidebarHistory.length > 1 && (
             <>
-              <SidebarChild item={parentItem} />
+              <SidebarChild />
               <DottedSeparator wrapperClassName="!my-0" />
             </>
           )}

www/packages/docs-ui/src/components/Sidebar/index.tsx

@@ -1,39 +1,35 @@
 "use client"
 
 import React, { Suspense, useMemo, useRef } from "react"
-import { isSidebarItemLink, useSidebar } from "@/providers"
+import { useSidebar } from "@/providers"
 import clsx from "clsx"
 import { Loading } from "@/components"
 import { SidebarItem } from "./Item"
 // @ts-expect-error can't install the types package because it doesn't support React v19
 import { CSSTransition, SwitchTransition } from "react-transition-group"
-import { SidebarTop, SidebarTopProps } from "./Top"
+import { SidebarTop } from "./Top"
 import { useClickOutside, useKeyboardShortcut } from "@/hooks"
 import useResizeObserver from "@react-hook/resize-observer"
+import { isSidebarItemLink } from "../../utils/sidebar-utils"
 
 export type SidebarProps = {
   className?: string
-  expandItems?: boolean
-  sidebarTopProps?: Omit<SidebarTopProps, "parentItem">
 }
 
-export const Sidebar = ({
-  className = "",
-  expandItems = true,
-  sidebarTopProps,
-}: SidebarProps) => {
+export const Sidebar = ({ className = "" }: SidebarProps) => {
   const sidebarWrapperRef = useRef(null)
   const sidebarTopRef = useRef<HTMLDivElement>(null)
   const {
-    items,
-    currentItems,
+    sidebars,
+    shownSidebar,
     mobileSidebarOpen,
     setMobileSidebarOpen,
-    staticSidebarItems,
+    isSidebarStatic,
     sidebarRef,
     desktopSidebarOpen,
     setDesktopSidebarOpen,
     setSidebarTopHeight,
+    sidebarHistory,
   } = useSidebar()
   useClickOutside({
     elmRef: sidebarWrapperRef,
@@ -51,15 +47,16 @@ export const Sidebar = ({
     },
   })
 
-  const sidebarItems = useMemo(
-    () => currentItems || items,
-    [items, currentItems]
-  )
-
   useResizeObserver(sidebarTopRef as React.RefObject<HTMLElement>, () => {
     setSidebarTopHeight(sidebarTopRef.current?.clientHeight || 0)
   })
 
+  const sidebarItems = useMemo(() => {
+    return shownSidebar && "items" in shownSidebar
+      ? shownSidebar.items
+      : shownSidebar?.children || []
+  }, [shownSidebar])
+
   return (
     <>
       {mobileSidebarOpen && (
@@ -94,7 +91,11 @@ export const Sidebar = ({
         <ul className={clsx("h-full w-full", "flex flex-col")}>
           <SwitchTransition>
             <CSSTransition
-              key={sidebarItems.parentItem?.title || "home"}
+              key={
+                sidebarHistory.length
+                  ? sidebarHistory[sidebarHistory.length - 1]
+                  : sidebars[0].sidebar_id
+              }
               nodeRef={sidebarRef}
               classNames={{
                 enter: "animate-fadeInLeft animate-fast",
@@ -110,32 +111,12 @@ export const Sidebar = ({
                 ref={sidebarRef}
                 id="sidebar"
               >
-                <SidebarTop
-                  {...sidebarTopProps}
-                  parentItem={sidebarItems.parentItem}
-                  ref={sidebarTopRef}
-                />
-                {/* MOBILE SIDEBAR - keeping this in case we need it in the future */}
-                {/* <div className={clsx("lg:hidden")}>
-                  {!sidebarItems.mobile.length && !staticSidebarItems && (
-                    <Loading className="px-0" />
-                  )}
-                  {sidebarItems.mobile.map((item, index) => (
-                    <SidebarItem
-                      item={item}
-                      key={index}
-                      expandItems={expandItems}
-                      hasNextItems={index !== sidebarItems.default.length - 1}
-                    />
-                  ))}
-                  {sidebarItems.mobile.length > 0 && <DottedSeparator />}
-                </div> */}
-                {/* DESKTOP SIDEBAR */}
+                <SidebarTop ref={sidebarTopRef} />
                 <div className="pt-docs_0.75">
-                  {!sidebarItems.default.length && !staticSidebarItems && (
-                    <Loading className="px-0" />
+                  {!sidebarItems.length && !isSidebarStatic && (
+                    <Loading className="px-docs_0.75" />
                   )}
-                  {sidebarItems.default.map((item, index) => {
+                  {sidebarItems.map((item, index) => {
                     const itemKey =
                       item.type === "separator"
                         ? index
@@ -155,10 +136,7 @@ export const Sidebar = ({
                       >
                         <SidebarItem
                           item={item}
-                          expandItems={expandItems}
-                          hasNextItems={
-                            index !== sidebarItems.default.length - 1
-                          }
+                          hasNextItems={index !== sidebarItems.length - 1}
                         />
                       </Suspense>
                     )

www/packages/docs-ui/src/hooks/use-child-docs/index.tsx

@@ -9,17 +9,17 @@ import {
   H3,
   H4,
   Hr,
-  isSidebarItemLink,
   LocalSearch,
   MarkdownContent,
   SearchInput,
   useIsBrowser,
   useSidebar,
 } from "../.."
-import { InteractiveSidebarItem, SidebarItem, SidebarItemLink } from "types"
+import { Sidebar } from "types"
 import slugify from "slugify"
 import { MDXComponents } from "../.."
 import { ChevronDoubleRight, ExclamationCircle } from "@medusajs/icons"
+import { isSidebarItemLink } from "../../utils/sidebar-utils"
 
 type HeadingComponent = (
   props: React.HTMLAttributes<HTMLHeadingElement>
@@ -60,11 +60,11 @@ export const useChildDocs = ({
     ...searchProps
   } = { enable: false },
 }: UseChildDocsProps) => {
-  const { currentItems, activeItem } = useSidebar()
+  const { shownSidebar, activeItem } = useSidebar()
   const { isBrowser } = useIsBrowser()
   const [searchQuery, setSearchQuery] = useState("")
   const [localSearch, setLocalSearch] = useState<
-    LocalSearch<SidebarItemLink> | undefined
+    LocalSearch<Sidebar.SidebarItemLink> | undefined
   >()
   const TitleHeaderComponent = useCallback(
     (level: number): HeadingComponent => {
@@ -91,7 +91,7 @@ export const useChildDocs = ({
         : "all"
   }, [showItems, hideItems])
 
-  const filterCondition = (item: SidebarItem): boolean => {
+  const filterCondition = (item: Sidebar.SidebarItem): boolean => {
     if (item.type === "separator") {
       return false
     }
@@ -111,8 +111,10 @@ export const useChildDocs = ({
     }
   }
 
-  const filterItems = (items: SidebarItem[]): InteractiveSidebarItem[] => {
-    return (items.filter(filterCondition) as InteractiveSidebarItem[])
+  const filterItems = (
+    items: Sidebar.SidebarItem[]
+  ): Sidebar.InteractiveSidebarItem[] => {
+    return (items.filter(filterCondition) as Sidebar.InteractiveSidebarItem[])
       .map((item) => Object.assign({}, item))
       .map((item) => {
         if (item.children && filterType === "hide") {
@@ -124,19 +126,19 @@ export const useChildDocs = ({
   }
 
   const filterNonInteractiveItems = (
-    items: SidebarItem[] | undefined
-  ): InteractiveSidebarItem[] => {
+    items: Sidebar.SidebarItem[] | undefined
+  ): Sidebar.InteractiveSidebarItem[] => {
     return (
       (items?.filter(
         (item) => item.type !== "separator"
-      ) as InteractiveSidebarItem[]) || []
+      ) as Sidebar.InteractiveSidebarItem[]) || []
     )
   }
 
   const getChildrenForLevel = (
-    item: InteractiveSidebarItem,
+    item: Sidebar.InteractiveSidebarItem,
     currentLevel = 1
-  ): InteractiveSidebarItem[] | undefined => {
+  ): Sidebar.InteractiveSidebarItem[] | undefined => {
     if (currentLevel === childLevel) {
       return filterNonInteractiveItems(item.children)
     }
@@ -144,7 +146,7 @@ export const useChildDocs = ({
       return
     }
 
-    const childrenResult: InteractiveSidebarItem[] = []
+    const childrenResult: Sidebar.InteractiveSidebarItem[] = []
 
     filterNonInteractiveItems(item.children).forEach((child) => {
       const childChildren = getChildrenForLevel(child, currentLevel + 1)
@@ -162,34 +164,24 @@ export const useChildDocs = ({
   const filteredItems = useMemo(() => {
     let targetItems =
       type === "sidebar"
-        ? currentItems
-          ? Object.assign({}, currentItems)
-          : undefined
-        : {
-            default: [...(activeItem?.children || [])],
-          }
+        ? shownSidebar && "items" in shownSidebar
+          ? shownSidebar.items
+          : shownSidebar?.children || []
+        : [...(activeItem?.children || [])]
     if (filterType !== "all" && targetItems) {
-      targetItems = {
-        ...targetItems,
-        default: filterItems(targetItems.default),
-      }
+      targetItems = filterItems(targetItems)
     }
 
-    return targetItems
-      ? {
-          ...targetItems,
-          default: filterNonInteractiveItems(targetItems?.default),
-        }
-      : undefined
-  }, [currentItems, type, activeItem, filterType])
+    return filterNonInteractiveItems(targetItems)
+  }, [shownSidebar, type, activeItem, filterType])
 
   const searchableItems = useMemo(() => {
-    const searchableItems: SidebarItemLink[] = []
+    const searchableItems: Sidebar.SidebarItemLink[] = []
     if (!enableSearch) {
       return searchableItems
     }
     if (onlyTopLevel) {
-      filteredItems?.default?.forEach((item) => {
+      filteredItems.forEach((item) => {
         if (isSidebarItemLink(item)) {
           searchableItems.push(item)
         } else {
@@ -197,16 +189,16 @@ export const useChildDocs = ({
             isSidebarItemLink(child)
           )
           if (firstChild) {
-            searchableItems.push(firstChild as SidebarItemLink)
+            searchableItems.push(firstChild as Sidebar.SidebarItemLink)
           }
         }
       })
     } else {
-      filteredItems?.default?.forEach((item) => {
-        const childItems: SidebarItemLink[] =
+      filteredItems?.forEach((item) => {
+        const childItems: Sidebar.SidebarItemLink[] =
           (getChildrenForLevel(item)?.filter((childItem) => {
             return isSidebarItemLink(childItem)
-          }) as SidebarItemLink[]) || []
+          }) as Sidebar.SidebarItemLink[]) || []
         searchableItems.push(...childItems)
       })
     }
@@ -224,7 +216,7 @@ export const useChildDocs = ({
     }
 
     setLocalSearch(
-      getLocalSearch<SidebarItemLink>({
+      getLocalSearch<Sidebar.SidebarItemLink>({
         docs: searchableItems,
         searchableFields: ["title", "description"],
         options: {
@@ -263,7 +255,7 @@ export const useChildDocs = ({
     localStorage.setItem(`${storageKey}-query`, searchQuery)
   }, [isBrowser, searchQuery, storageKey, enableSearch])
 
-  const getTopLevelElms = (items?: InteractiveSidebarItem[]) => {
+  const getTopLevelElms = (items?: Sidebar.InteractiveSidebarItem[]) => {
     return (
       <CardList
         items={
@@ -274,7 +266,7 @@ export const useChildDocs = ({
                 ? (
                     childItem.children.find((item) =>
                       isSidebarItemLink(item)
-                    ) as SidebarItemLink
+                    ) as Sidebar.SidebarItemLink
                   )?.path
                 : "#"
             return {
@@ -292,7 +284,7 @@ export const useChildDocs = ({
   }
 
   const getAllLevelsElms = (
-    items?: InteractiveSidebarItem[],
+    items?: Sidebar.InteractiveSidebarItem[],
     headerLevel = titleLevel
   ) => {
     return items?.map((item, key) => {
@@ -405,8 +397,8 @@ export const useChildDocs = ({
         {!searchQuery && (
           <>
             {onlyTopLevel
-              ? getTopLevelElms(filteredItems?.default)
-              : getAllLevelsElms(filteredItems?.default)}
+              ? getTopLevelElms(filteredItems)
+              : getAllLevelsElms(filteredItems)}
           </>
         )}
       </>

www/packages/docs-ui/src/layouts/main-content.tsx

@@ -1,9 +1,8 @@
 "use client"
 
 import React, { useEffect } from "react"
-import { useSidebar } from "../providers/Sidebar"
 import clsx from "clsx"
-import { MainNav, useIsBrowser, useLayout } from ".."
+import { MainNav, useIsBrowser, useLayout, useSidebar } from ".."
 
 export type MainContentLayoutProps = {
   mainWrapperClasses?: string

www/packages/docs-ui/src/providers/Pagination/index.tsx

@@ -1,15 +1,10 @@
 "use client"
 
-import React, {
-  createContext,
-  useContext,
-  useEffect,
-  useMemo,
-  useState,
-} from "react"
-import { isSidebarItemLink, useSidebar } from "../Sidebar"
+import React, { createContext, useContext, useEffect, useState } from "react"
 import { usePrevious } from "@uidotdev/usehooks"
-import { InteractiveSidebarItem, SidebarItem } from "types"
+import { useSidebar } from "../Sidebar"
+import { isSidebarItemLink } from "../../utils/sidebar-utils"
+import { Sidebar } from "types"
 
 export type Page = {
   title: string
@@ -27,8 +22,8 @@ export const PaginationContext = createContext<PaginationContextType | null>(
   null
 )
 
-type SidebarItemWithParent = InteractiveSidebarItem & {
-  parent?: SidebarItem
+type SidebarItemWithParent = Sidebar.InteractiveSidebarItem & {
+  parent?: Sidebar.InteractiveSidebarItem
 }
 
 type SearchItemsResult = {
@@ -42,14 +37,13 @@ export type PaginationProviderProps = {
 }
 
 export const PaginationProvider = ({ children }: PaginationProviderProps) => {
-  const { items, activePath } = useSidebar()
-  const combinedItems = useMemo(() => [...items.default], [items])
+  const { shownSidebar, activePath } = useSidebar()
   const previousActivePath = usePrevious(activePath)
   const [nextPage, setNextPage] = useState<Page | undefined>()
   const [prevPage, setPrevPage] = useState<Page | undefined>()
 
   const getFirstChild = (
-    item: InteractiveSidebarItem
+    item: Sidebar.InteractiveSidebarItem
   ): SidebarItemWithParent | undefined => {
     const children = getChildrenWithPages(item)
     if (!children?.length) {
@@ -65,7 +59,7 @@ export const PaginationProvider = ({ children }: PaginationProviderProps) => {
   }
 
   const getChildrenWithPages = (
-    item: InteractiveSidebarItem
+    item: Sidebar.InteractiveSidebarItem
   ): SidebarItemWithParent[] | undefined => {
     return item.children?.filter(
       (childItem) =>
@@ -76,7 +70,7 @@ export const PaginationProvider = ({ children }: PaginationProviderProps) => {
   }
 
   const getPrevItem = (
-    items: SidebarItem[],
+    items: Sidebar.SidebarItem[],
     index: number
   ): SidebarItemWithParent | undefined => {
     let foundItem: SidebarItemWithParent | undefined
@@ -106,7 +100,7 @@ export const PaginationProvider = ({ children }: PaginationProviderProps) => {
   }
 
   const getNextItem = (
-    items: SidebarItem[],
+    items: Sidebar.SidebarItem[],
     index: number
   ): SidebarItemWithParent | undefined => {
     let foundItem: SidebarItemWithParent | undefined
@@ -133,7 +127,9 @@ export const PaginationProvider = ({ children }: PaginationProviderProps) => {
     return foundItem
   }
 
-  const searchItems = (currentItems: SidebarItem[]): SearchItemsResult => {
+  const searchItems = (
+    currentItems: Sidebar.SidebarItem[]
+  ): SearchItemsResult => {
     const result: SearchItemsResult = {
       foundActive: false,
     }
@@ -182,7 +178,11 @@ export const PaginationProvider = ({ children }: PaginationProviderProps) => {
 
   useEffect(() => {
     if (activePath !== previousActivePath) {
-      const result = searchItems(combinedItems)
+      const sidebarItems =
+        shownSidebar && "items" in shownSidebar
+          ? shownSidebar.items
+          : shownSidebar?.children || []
+      const result = searchItems(sidebarItems)
       setPrevPage(
         result.prevItem
           ? {
@@ -190,10 +190,7 @@ export const PaginationProvider = ({ children }: PaginationProviderProps) => {
               link: isSidebarItemLink(result.prevItem)
                 ? result.prevItem.path
                 : "",
-              parentTitle:
-                result.prevItem.parent?.type !== "separator"
-                  ? result.prevItem.parent?.title
-                  : undefined,
+              parentTitle: result.prevItem.parent?.title,
             }
           : undefined
       )
@@ -204,10 +201,7 @@ export const PaginationProvider = ({ children }: PaginationProviderProps) => {
               link: isSidebarItemLink(result.nextItem)
                 ? result.nextItem.path
                 : "",
-              parentTitle:
-                result.nextItem.parent?.type !== "separator"
-                  ? result.nextItem.parent?.title
-                  : undefined,
+              parentTitle: result.nextItem?.parent?.title,
             }
           : undefined
       )

www/packages/docs-ui/src/providers/Sidebar/index.tsx

@@ -1,7 +1,6 @@
 "use client"
 
 import React, {
-  ReactNode,
   createContext,
   useCallback,
   useContext,
@@ -11,224 +10,180 @@ import React, {
   useRef,
   useState,
 } from "react"
-import { usePathname, useRouter } from "next/navigation"
-import { getScrolledTop } from "@/utils"
+import { Sidebar } from "types"
 import {
-  SidebarItemSections,
-  SidebarItem,
-  SidebarSectionItems,
-  SidebarItemLink,
-  InteractiveSidebarItem,
-  SidebarItemCategory,
-  SidebarItemLinkWithParent,
-  InteractiveSidebarItemTypes,
-} from "types"
+  areSidebarItemsEqual,
+  findSidebarItem,
+  getSidebarItemWithHistory,
+  isSidebarItemLink,
+} from "../../utils/sidebar-utils"
+import { useSiteConfig } from "../SiteConifg"
 import { useIsBrowser } from "../BrowserProvider"
+import { getScrolledTop } from "../../utils"
+import { usePathname, useRouter } from "next/navigation"
 
-export type CurrentItemsState = SidebarSectionItems & {
-  previousSidebar?: CurrentItemsState
+export type SidebarActionOptions = {
+  sidebar_id: string
+  /**
+   * When specified, the items are added as children of the parent item
+   */
+  parent?: {
+    type: Sidebar.InteractiveSidebarItemTypes
+    path: string
+    title: string
+    /**
+     * Whether to change the loaded state of the parent item
+     */
+    changeLoaded?: boolean
+  }
+  /**
+   * The position to insert the items at
+   */
+  indexPosition?: number
+  /**
+   * If enabled, the items are filtered to not add items that already exist
+   */
+  ignoreExisting?: boolean
 }
 
 export type SidebarStyleOptions = {
+  /**
+   * Useful for projects that have nested sidebars.
+   */
   disableActiveTransition?: boolean
 }
 
 export type SidebarContextType = {
-  items: SidebarSectionItems
-  currentItems: CurrentItemsState | undefined
+  sidebars: Sidebar.Sidebar[]
+  /**
+   * The sidebar that is currently shown
+   */
+  shownSidebar: Sidebar.Sidebar | Sidebar.SidebarItemSidebar | undefined
   activePath: string | null
-  activeItem: SidebarItemLinkWithParent | undefined
+  activeItem: Sidebar.SidebarItemLink | null
   setActivePath: (path: string | null) => void
-  isLinkActive: (item: SidebarItem, checkChildren?: boolean) => boolean
-  isChildrenActive: (item: SidebarItemCategory) => boolean
-  addItems: (items: SidebarItem[], options?: ActionOptionsType) => void
-  removeItems: (items: SidebarItem[]) => void
-  findItemInSection: (
-    section: SidebarItem[],
-    item: Partial<SidebarItem>,
-    checkChildren?: boolean
-  ) => SidebarItem | undefined
+  /**
+   * Check if an item is active. This includes checking its child items,
+   * so for UI links that have children, the `checkLinkChildren` option should be set to `false`
+   * to ensure that the link isn't shown as active if a child link is active.
+   */
+  isItemActive: (options: {
+    item: Sidebar.InteractiveSidebarItem
+    checkLinkChildren?: boolean
+  }) => boolean
+  addItems: (
+    items: Sidebar.SidebarItem[],
+    options?: SidebarActionOptions
+  ) => void
+  removeItems: (options: {
+    items: Sidebar.SidebarItem[]
+    sidebar_id: string
+  }) => void
   mobileSidebarOpen: boolean
   setMobileSidebarOpen: React.Dispatch<React.SetStateAction<boolean>>
   desktopSidebarOpen: boolean
   setDesktopSidebarOpen: React.Dispatch<React.SetStateAction<boolean>>
-  staticSidebarItems?: boolean
+  // Whether the items in the sidebar are static or are added dynamically
+  // TODO look into generating the sidebar item of the API reference
+  isSidebarStatic: boolean
+  /**
+   * Whether the active path should change when the hash changes
+   * This is only used by the API reference
+   */
   shouldHandleHashChange: boolean
   sidebarRef: React.RefObject<HTMLDivElement | null>
+  /**
+   * Go back in the sidebar history
+   */
   goBack: () => void
+  /**
+   * The height of the top part of the sidebar
+   */
   sidebarTopHeight: number
   setSidebarTopHeight: React.Dispatch<React.SetStateAction<number>>
+  /**
+   * Reset the sidebar to its initial state (the sidebars passed as a prop)
+   */
   resetItems: () => void
-  isItemLoaded: (path: string) => boolean
   updatePersistedCategoryState: (title: string, opened: boolean) => void
   getPersistedCategoryState: (title: string) => boolean | undefined
-  persistState: boolean
+  persistCategoryState: boolean
   isSidebarShown: boolean
+  sidebarHistory: string[]
+  /**
+   * Get the first link child of a sidebar
+   */
+  getSidebarFirstLinkChild: (
+    sidebar: Sidebar.Sidebar | Sidebar.SidebarItemSidebar
+  ) => Sidebar.SidebarItemLink | undefined
+  getSidebar: (
+    sidebar_id: string
+  ) => Sidebar.Sidebar | Sidebar.SidebarItemSidebar
 } & SidebarStyleOptions
 
 export const SidebarContext = createContext<SidebarContextType | null>(null)
 
-export type ActionOptionsType = {
-  section?: SidebarItemSections
-  parent?: {
-    type: InteractiveSidebarItemTypes
-    path: string
-    title: string
-    changeLoaded?: boolean
-  }
-  indexPosition?: number
-  ignoreExisting?: boolean
-}
-
 export type ActionType =
   | {
       type: "add" | "update"
-      items: SidebarItem[]
-      options?: ActionOptionsType
+      items: Sidebar.SidebarItem[]
+      options?: SidebarActionOptions
     }
   | {
       type: "replace"
-      replacementItems: SidebarSectionItems
+      sidebars: Sidebar.Sidebar[]
     }
   | {
       type: "remove"
-      items: SidebarItem[]
-    }
-
-type LinksMap = Map<string, SidebarItemLinkWithParent>
-
-export const isSidebarItemLink = (
-  item: SidebarItem | undefined,
-  checkRef = true
-): item is SidebarItemLink => {
-  return (
-    item !== undefined &&
-    (item.type === "link" || (checkRef && item.type === "ref"))
-  )
-}
-
-const areItemsEqual = (
-  itemA: SidebarItem,
-  itemB: SidebarItem,
-  compareTitles = true
-): boolean => {
-  if (
-    itemA.type === "separator" ||
-    itemB.type === "separator" ||
-    itemA.type !== itemB.type
-  ) {
-    return false
-  }
-  const hasSameTitle = !compareTitles || itemA.title === itemB.title
-  const hasSamePath =
-    !isSidebarItemLink(itemA) ||
-    !isSidebarItemLink(itemB) ||
-    itemA.path === itemB.path
-
-  return hasSameTitle && hasSamePath
-}
-
-const findItem = (
-  section: SidebarItem[],
-  item: Partial<SidebarItem>,
-  checkChildren = true,
-  compareTitles = true
-): SidebarItemLinkWithParent | undefined => {
-  let foundItem: SidebarItemLinkWithParent | undefined
-  section.some((i) => {
-    if (i.type === "separator") {
-      return false
-    }
-    if (areItemsEqual(item as SidebarItem, i, compareTitles)) {
-      foundItem = i as SidebarItemLink
-    } else if (checkChildren && i.children) {
-      foundItem = findItem(i.children, item, checkChildren, compareTitles)
-      if (foundItem && !foundItem.parentItem) {
-        foundItem.parentItem = i
-      }
-    }
-
-    return foundItem !== undefined
-  })
-
-  return foundItem
-}
-
-const getLinksMap = (
-  items: SidebarItem[],
-  initMap?: LinksMap,
-  parentItem?: InteractiveSidebarItem
-): LinksMap => {
-  const map: LinksMap = initMap || new Map()
-
-  items.forEach((item) => {
-    if (item.type === "separator") {
-      return
-    }
-
-    if (isSidebarItemLink(item)) {
-      map.set(item.path, {
-        ...item,
-        parentItem,
-      })
-    }
-    if (item.children?.length) {
-      getLinksMap(item.children, map, item)
-    }
-  })
-
-  return map
+      items: Sidebar.SidebarItem[]
+      sidebar_id: string
     }
 
 export const reducer = (
-  state: SidebarSectionItems,
+  state: Sidebar.Sidebar[],
   actionData: ActionType
-): SidebarSectionItems => {
+): Sidebar.Sidebar[] => {
   if (actionData.type === "replace") {
-    return actionData.replacementItems
+    return actionData.sidebars
   }
   if (actionData.type === "remove") {
+    const { sidebar_id, items: itemsToRemove } = actionData
+    return state.map((sidebar) => {
+      if (sidebar.sidebar_id === sidebar_id) {
         return {
-      ...state,
-      default: state.default.filter((item) => {
-        if (item.type === "separator") {
-          return true
-        }
-
-        const found = actionData.items.some((itemToRemove) => {
-          if (
-            itemToRemove.type === "separator" ||
-            itemToRemove.type !== item.type
-          ) {
-            return false
-          }
-
-          if (
-            itemToRemove.type === "category" ||
-            itemToRemove.type === "sub-category"
-          ) {
-            return itemToRemove.title === item.title
-          }
-
-          return (
-            itemToRemove.path === (item as SidebarItemLink).path &&
-            itemToRemove.title === (item as SidebarItemLink).title
-          )
+          ...sidebar,
+          items: sidebar.items.filter((item) => {
+            return !itemsToRemove.some((itemToRemove) =>
+              areSidebarItemsEqual({
+                itemA: item,
+                itemB: itemToRemove,
               })
-
-        return !found
+            )
           }),
         }
       }
+      return sidebar
+    })
+  }
+
   const { type, options } = actionData
   let { items } = actionData
 
   const { parent, ignoreExisting = false, indexPosition } = options || {}
-  const sectionName = SidebarItemSections.DEFAULT
-  const sectionItems = state[sectionName]
+  const sidebarIndex = state.findIndex(
+    (s) => s.sidebar_id === options?.sidebar_id
+  )
+  const sidebar = state[sidebarIndex]
+
+  if (!sidebar) {
+    return state
+  }
 
   if (!ignoreExisting) {
-    items = items.filter((item) => !findItem(sectionItems, item))
+    items = items.filter(
+      (item) =>
+        findSidebarItem({ sidebarItems: sidebar.items, item }) === undefined
+    )
   }
 
   if (!items.length) {
@@ -237,26 +192,38 @@ export const reducer = (
 
   switch (type) {
     case "add":
-      return {
-        ...state,
-        [sectionName]:
+      return [
+        ...state.slice(0, sidebarIndex),
+        {
+          ...sidebar,
+          items:
             indexPosition !== undefined
               ? [
-                ...sectionItems.slice(0, indexPosition),
+                  ...sidebar.items.slice(0, indexPosition),
                   ...items,
-                ...sectionItems.slice(indexPosition),
+                  ...sidebar.items.slice(indexPosition),
+                ]
+              : [...sidebar.items, ...items],
+        },
+        ...state.slice(sidebarIndex + 1),
       ]
-            : [...sectionItems, ...items],
-      }
     case "update":
       // find item index
-      return {
-        ...state,
-        [sectionName]: sectionItems.map((i) => {
+      return [
+        ...state.slice(0, sidebarIndex),
+        {
+          ...sidebar,
+          items: sidebar.items.map((i) => {
             if (i.type === "separator") {
               return i
             }
-          if (parent && areItemsEqual(i, parent as SidebarItem)) {
+            if (
+              parent &&
+              areSidebarItemsEqual({
+                itemA: i,
+                itemB: parent as Sidebar.InteractiveSidebarItem,
+              })
+            ) {
               return {
                 ...i,
                 children:
@@ -276,75 +243,155 @@ export const reducer = (
             }
             return i
           }),
-      }
+        },
+        ...state.slice(sidebarIndex + 1),
+      ]
     default:
       return state
   }
 }
 
 export type SidebarProviderProps = {
-  children?: ReactNode
+  children?: React.ReactNode
   isLoading?: boolean
   setIsLoading?: React.Dispatch<React.SetStateAction<boolean>>
-  initialItems?: SidebarSectionItems
+  sidebars: Sidebar.Sidebar[]
   shouldHandleHashChange?: boolean
   shouldHandlePathChange?: boolean
   scrollableElement?: Element | Window
-  staticSidebarItems?: boolean
-  resetOnCondition?: () => boolean
-  projectName: string
-  persistState?: boolean
+  isSidebarStatic?: boolean
+  persistCategoryState?: boolean
+  disableActiveTransition?: boolean
 } & SidebarStyleOptions
 
 export const SidebarProvider = ({
   children,
-  isLoading = false,
+  isLoading,
   setIsLoading,
-  initialItems,
+  sidebars: initialSidebars = [],
   shouldHandleHashChange = false,
-  shouldHandlePathChange = false,
+  shouldHandlePathChange = true,
   scrollableElement,
-  staticSidebarItems = false,
-  disableActiveTransition = false,
-  resetOnCondition,
-  projectName,
-  persistState = true,
+  isSidebarStatic = true,
+  persistCategoryState = true,
+  disableActiveTransition = true,
 }: SidebarProviderProps) => {
-  const categoriesStorageKey = `${projectName}_categories`
+  const {
+    config: { project },
+  } = useSiteConfig()
+  const categoriesStorageKey = `${project.title}_categories`
   const hideSidebarStorageKey = `hide_sidebar`
-  const [items, dispatch] = useReducer(reducer, {
-    default: initialItems?.default || [],
-    mobile: initialItems?.mobile || [],
-  })
-  const [currentItems, setCurrentItems] = useState<
-    CurrentItemsState | undefined
-  >()
+  const [sidebars, dispatch] = useReducer(reducer, initialSidebars)
   const [activePath, setActivePath] = useState<string | null>("")
-  const linksMap: LinksMap = useMemo(() => {
-    return new Map([
-      ...getLinksMap(items.mobile),
-      ...getLinksMap(items.default),
-    ])
-  }, [items])
-  const findItemInSection = useCallback(findItem, [])
-  const activeItem = useMemo(() => {
-    if (activePath === null) {
-      return undefined
-    }
-
-    return linksMap.get(activePath)
-  }, [activePath, linksMap])
   const [mobileSidebarOpen, setMobileSidebarOpen] = useState<boolean>(false)
-  const [sidebarTopHeight, setSidebarTopHeight] = useState(0)
   const [desktopSidebarOpen, setDesktopSidebarOpen] = useState(true)
   const sidebarRef = useRef<HTMLDivElement>(null)
+  const [sidebarTopHeight, setSidebarTopHeight] = useState(0)
 
   const pathname = usePathname()
   const router = useRouter()
   const { isBrowser } = useIsBrowser()
-  const getResolvedScrollableElement = useCallback(() => {
+
+  const resolvedScrollableElement = useMemo(() => {
+    if (!isBrowser) {
+      return
+    }
+
     return scrollableElement || window
-  }, [scrollableElement])
+  }, [scrollableElement, isBrowser])
+
+  const activeMainSidebar = useMemo(() => {
+    if (!activePath) {
+      // set first sidebar as active
+      return sidebars[0]
+    }
+    return (
+      sidebars.find(
+        (s) =>
+          findSidebarItem({
+            sidebarItems: s.items,
+            item: { type: "link", path: activePath, title: "" },
+          }) !== undefined
+      ) || sidebars[0]
+    )
+  }, [sidebars, activePath])
+
+  const { activeItem, sidebarHistory } = useMemo(() => {
+    if (!activePath) {
+      return {
+        activeItem: null,
+        sidebarHistory: [] as string[],
+      }
+    }
+    const result =
+      getSidebarItemWithHistory({
+        sidebarItems: activeMainSidebar.items,
+        item: { type: "link", path: activePath, title: "" },
+        compareTitles: false,
+      }) || null
+
+    return {
+      ...result,
+      sidebarHistory: [
+        activeMainSidebar.sidebar_id,
+        ...(result.sidebarHistory || []),
+      ],
+      activeItem: (result.item as Sidebar.SidebarItemLink) || null,
+    }
+  }, [activePath, activeMainSidebar])
+
+  const getSidebar = useCallback(
+    (sidebar_id: string) => {
+      return (
+        sidebars.find((s) => s.sidebar_id === sidebar_id) ||
+        (findSidebarItem({
+          sidebarItems: activeMainSidebar.items || [],
+          item: { type: "sidebar", sidebar_id, title: "" },
+          compareTitles: false,
+        }) as Sidebar.SidebarItemSidebar)
+      )
+    },
+    [sidebars, activeMainSidebar]
+  )
+
+  const shownSidebar = useMemo(() => {
+    if (!sidebarHistory.length) {
+      return
+    }
+
+    return getSidebar(sidebarHistory[sidebarHistory.length - 1])
+  }, [activeMainSidebar, sidebarHistory, getSidebar])
+
+  const isItemActive: SidebarContextType["isItemActive"] = useCallback(
+    ({ item, checkLinkChildren = true }): boolean => {
+      if (!activePath) {
+        return false
+      }
+
+      if (isSidebarItemLink(item)) {
+        if (item.path === activePath) {
+          return true
+        } else if (!checkLinkChildren) {
+          return false
+        }
+      }
+
+      return (
+        item.children?.some((child) => {
+          if (child.type === "separator") {
+            return false
+          }
+
+          return isItemActive({
+            item: child as Sidebar.InteractiveSidebarItem,
+            checkLinkChildren,
+          })
+        }) || false
+      )
+    },
+    [activePath]
+  )
+
   const isSidebarShown = useMemo(() => {
     if (!isBrowser) {
       return true
@@ -353,16 +400,10 @@ export const SidebarProvider = ({
     return document.getElementsByTagName("aside").length > 0
   }, [isBrowser])
 
-  const isItemLoaded = useCallback(
-    (path: string) => {
-      const item = linksMap.get(path)
-
-      return item?.loaded || false
-    },
-    [items, linksMap]
-  )
-
-  const addItems = (newItems: SidebarItem[], options?: ActionOptionsType) => {
+  const addItems = (
+    newItems: Sidebar.SidebarItem[],
+    options?: SidebarActionOptions
+  ) => {
     dispatch({
       type: options?.parent ? "update" : "add",
       items: newItems,
@@ -370,123 +411,39 @@ export const SidebarProvider = ({
     })
   }
 
-  const removeItems = (itemsToRemove: SidebarItem[]) => {
+  const removeItems = ({
+    items,
+    sidebar_id,
+  }: {
+    items: Sidebar.SidebarItem[]
+    sidebar_id: string
+  }) => {
     dispatch({
       type: "remove",
-      items: itemsToRemove,
+      items,
+      sidebar_id,
     })
   }
 
-  const isLinkActive = useCallback(
-    (item: SidebarItem, checkChildren = false, checkRef = true): boolean => {
-      if (!isSidebarItemLink(item, checkRef)) {
-        return false
-      }
-
-      return (
-        item.path === activePath ||
-        (checkChildren && activePath?.split("_")[0] === item.path)
-      )
-    },
-    [activePath]
-  )
-
-  const isChildrenActive = useCallback(
-    (item: InteractiveSidebarItem): boolean => {
-      return (
-        item.children?.some((child) => {
-          if (isLinkActive(child, true)) {
-            return true
-          }
-
-          return child.type !== "separator" && child.children
-            ? isChildrenActive(child)
-            : false
-        }) || false
-      )
-    },
-    [isLinkActive]
-  )
-
-  const init = () => {
-    const currentPath = location.hash.replace("#", "")
-    if (currentPath) {
-      setActivePath(currentPath)
-    }
-  }
-
-  const getCurrentSidebar = useCallback(
-    (searchItems: SidebarItem[]): InteractiveSidebarItem | undefined => {
-      let currentSidebar: InteractiveSidebarItem | undefined
-      searchItems.some((item) => {
-        if (item.type === "separator") {
-          return false
-        }
-        if (item.isChildSidebar && isLinkActive(item, false, false)) {
-          currentSidebar = item
-          return true
-        }
-        if (!item.children?.length) {
-          return false
-        }
-
-        const childSidebar =
-          getCurrentSidebar(item.children) ||
-          (activePath
-            ? findItem(
-                item.children,
-                {
-                  path: activePath,
-                  type: "link",
-                },
-                true,
-                false
-              )
-            : undefined)
-
-        currentSidebar = childSidebar
-          ? childSidebar.isChildSidebar
-            ? childSidebar
-            : item
-          : undefined
-
-        return currentSidebar !== undefined
-      })
-
-      return currentSidebar
-    },
-    [isLinkActive, activePath]
-  )
-
-  const goBack = () => {
-    if (!currentItems) {
-      return
-    }
-
-    const previousSidebar = currentItems.previousSidebar || items
-
-    const backItem = previousSidebar.default.find(
-      (item) => isSidebarItemLink(item) && !item.isChildSidebar
-    ) as SidebarItemLink
-
-    if (!backItem) {
-      return
-    }
-
-    setActivePath(backItem.path!)
-    setCurrentItems(previousSidebar)
-    router.replace(backItem.path!)
-  }
-
   const resetItems = useCallback(() => {
     dispatch({
       type: "replace",
-      replacementItems: {
-        default: initialItems?.default || [],
-        mobile: initialItems?.mobile || [],
-      },
+      sidebars: initialSidebars,
     })
-  }, [initialItems])
+  }, [initialSidebars])
+
+  const init = () => {
+    const currentPath = location.hash.replace("#", "")
+    if (currentPath) {
+      setActivePath(currentPath)
+    } else {
+      const firstChild = getFirstLinkChild(activeMainSidebar.items)
+
+      if (firstChild) {
+        setActivePath(firstChild.path)
+      }
+    }
+  }
 
   useEffect(() => {
     if (shouldHandleHashChange) {
@@ -495,21 +452,17 @@ export const SidebarProvider = ({
   }, [shouldHandleHashChange])
 
   useEffect(() => {
-    if (!shouldHandleHashChange) {
+    if (!shouldHandleHashChange || !resolvedScrollableElement) {
       return
     }
 
-    const resolvedScrollableElement = getResolvedScrollableElement()
-
     const handleScroll = () => {
       if (getScrolledTop(resolvedScrollableElement) === 0) {
-        const firstItemPath =
-          items.default.length && isSidebarItemLink(items.default[0])
-            ? items.default[0].path
-            : ""
-        setActivePath(firstItemPath)
-        if (firstItemPath) {
-          router.push(`#${firstItemPath}`, {
+        const firstChild = getFirstLinkChild(activeMainSidebar.items)
+
+        if (firstChild) {
+          setActivePath(firstChild.path)
+          router.push(`#${firstChild.path}`, {
             scroll: false,
           })
         }
@@ -521,7 +474,7 @@ export const SidebarProvider = ({
     return () => {
       resolvedScrollableElement.removeEventListener("scroll", handleScroll)
     }
-  }, [shouldHandleHashChange, getResolvedScrollableElement])
+  }, [shouldHandleHashChange, resolvedScrollableElement])
 
   useEffect(() => {
     if (!shouldHandleHashChange || !isBrowser) {
@@ -544,10 +497,10 @@ export const SidebarProvider = ({
   }, [shouldHandleHashChange, isBrowser])
 
   useEffect(() => {
-    if (isLoading && items.default.length) {
+    if (isLoading && sidebars.length) {
       setIsLoading?.(false)
     }
-  }, [items, isLoading, setIsLoading])
+  }, [sidebars, isLoading, setIsLoading])
 
   useEffect(() => {
     if (!shouldHandlePathChange) {
@@ -559,47 +512,6 @@ export const SidebarProvider = ({
     }
   }, [shouldHandlePathChange, pathname])
 
-  useEffect(() => {
-    if (!activePath?.length) {
-      setCurrentItems(undefined)
-      return
-    }
-
-    const currentSidebar = getCurrentSidebar(items.default)
-
-    if (!currentSidebar) {
-      setCurrentItems(undefined)
-      return
-    }
-
-    if (
-      currentSidebar.isChildSidebar &&
-      currentSidebar.children &&
-      (!currentItems?.parentItem ||
-        !areItemsEqual(currentItems?.parentItem, currentSidebar))
-    ) {
-      const { children, ...parentItem } = currentSidebar
-      const hasPreviousSidebar =
-        isSidebarItemLink(currentItems?.previousSidebar?.parentItem) &&
-        isSidebarItemLink(parentItem) &&
-        currentItems.previousSidebar.parentItem.path !== parentItem.path
-
-      setCurrentItems({
-        default: children,
-        mobile: items.mobile,
-        parentItem: parentItem,
-        previousSidebar: hasPreviousSidebar ? currentItems : undefined,
-      })
-    }
-  }, [getCurrentSidebar, activePath])
-
-  useEffect(() => {
-    if (resetOnCondition?.()) {
-      resetItems()
-      setActivePath(null)
-    }
-  }, [resetOnCondition, resetItems])
-
   useEffect(() => {
     if (!isBrowser) {
       return
@@ -627,12 +539,12 @@ export const SidebarProvider = ({
     const storageData = JSON.parse(
       localStorage.getItem(categoriesStorageKey) || "{}"
     )
-    if (!Object.hasOwn(storageData, projectName)) {
-      storageData[projectName] = {}
+    if (!Object.hasOwn(storageData, project.title)) {
+      storageData[project.title] = {}
     }
 
-    storageData[projectName] = {
-      ...storageData[projectName],
+    storageData[project.title] = {
+      ...storageData[project.title],
       [title]: opened,
     }
 
@@ -644,42 +556,98 @@ export const SidebarProvider = ({
       localStorage.getItem(categoriesStorageKey) || "{}"
     )
 
-    return !Object.hasOwn(storageData, projectName) ||
-      !Object.hasOwn(storageData[projectName], title)
+    return !Object.hasOwn(storageData, project.title) ||
+      !Object.hasOwn(storageData[project.title], title)
       ? undefined
-      : storageData[projectName][title]
+      : storageData[project.title][title]
+  }
+
+  const getFirstLinkChild = useCallback(
+    (items: Sidebar.SidebarItem[]): Sidebar.SidebarItemLink | undefined => {
+      let foundItem: Sidebar.SidebarItemLink | undefined
+      items.some((item) => {
+        if (item.type === "link") {
+          foundItem = item
+        } else if ("children" in item && item.children) {
+          foundItem = getFirstLinkChild(item.children)
+        }
+
+        return foundItem !== undefined
+      })
+
+      return foundItem
+    },
+    []
+  )
+
+  const getSidebarFirstLinkChild = useCallback(
+    (
+      sidebar: Sidebar.Sidebar | Sidebar.SidebarItemSidebar
+    ): Sidebar.SidebarItemLink | undefined => {
+      const itemsToSearch =
+        "items" in sidebar ? sidebar.items : sidebar.children || []
+
+      return getFirstLinkChild(itemsToSearch)
+    },
+    [getFirstLinkChild]
+  )
+
+  const openSidebar = (sidebar_id: string) => {
+    const sidebar = getSidebar(sidebar_id)
+    if (!sidebar) {
+      return
+    }
+
+    const firstChild = getSidebarFirstLinkChild(sidebar)
+
+    if (firstChild) {
+      setActivePath(firstChild.path)
+      router.replace(
+        firstChild.isPathHref ? firstChild.path : `#${firstChild.path}`
+      )
+    }
+  }
+
+  const goBack = () => {
+    if (!sidebarHistory || sidebarHistory.length <= 1) {
+      openSidebar(activeMainSidebar.sidebar_id)
+    } else {
+      const lastSidebar = sidebarHistory[sidebarHistory.length - 2]
+
+      openSidebar(lastSidebar)
+    }
   }
 
   return (
     <SidebarContext.Provider
       value={{
-        items,
-        currentItems,
+        sidebars,
+        shownSidebar,
+        activePath,
+        activeItem,
+        setActivePath,
+        isItemActive,
         addItems,
         removeItems,
-        activePath,
-        setActivePath,
-        isLinkActive: isLinkActive,
-        isChildrenActive,
-        findItemInSection,
         mobileSidebarOpen,
         setMobileSidebarOpen,
         desktopSidebarOpen,
         setDesktopSidebarOpen,
-        activeItem,
-        staticSidebarItems,
-        disableActiveTransition,
+        isSidebarStatic,
         shouldHandleHashChange,
         sidebarRef,
         goBack,
         sidebarTopHeight,
         setSidebarTopHeight,
         resetItems,
-        isItemLoaded,
         updatePersistedCategoryState,
         getPersistedCategoryState,
-        persistState,
+        persistCategoryState,
         isSidebarShown,
+        sidebarHistory,
+        getSidebarFirstLinkChild,
+        getSidebar,
+        disableActiveTransition,
       }}
     >
       {children}

www/packages/docs-ui/src/providers/SiteConifg/index.tsx

@@ -25,17 +25,11 @@ export const SiteConfigProvider = ({
     Object.assign(
       {
         baseUrl: "",
-        sidebar: {
-          default: [],
-          mobile: [],
-        },
+        sidebars: [],
         project: {
           title: "",
           key: "",
         },
-        breadcrumbOptions: {
-          showCategories: true,
-        },
         reportIssueLink: GITHUB_ISSUES_LINK,
         logo: "",
       },

www/packages/docs-ui/src/utils/get-local-search.ts

@@ -21,7 +21,8 @@ export const getLocalSearch = <T extends BaseSearchRecord = BaseSearchRecord>({
   docs,
   searchableFields,
   options,
-}: GetLocalSearchInput<T>): LocalSearch<T> => {
+}: GetLocalSearchInput<T>): LocalSearch<T> | undefined => {
+  try {
     const miniSearch = new MiniSearch({
       fields: searchableFields,
       ...options,
@@ -29,4 +30,7 @@ export const getLocalSearch = <T extends BaseSearchRecord = BaseSearchRecord>({
     miniSearch.addAll(docs)
 
     return miniSearch as LocalSearch<T>
+  } catch (e) {
+    console.warn(e)
+  }
 }

www/packages/docs-ui/src/utils/index.ts

@@ -12,6 +12,6 @@ export * from "./is-elm-window"
 export * from "./is-in-view"
 export * from "./learning-paths"
 export * from "./set-obj-value"
-export * from "./sidebar-attach-href-common-options"
+export * from "./sidebar-utils"
 export * from "./swr-fetcher"
 export * from "./workflow-diagram-utils"