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,23 +85,24 @@ 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) {
-        const elm = document.getElementById(tagName[0])
-        if (elm && !checkElementInViewport(elm, 0)) {
-          scrollToTop(
-            elm.offsetTop + (elm.offsetParent as HTMLElement)?.offsetTop,
-            0
-          )
-        }
-      } else if (tagName.length > 1 && tagName[0] === slugTagName) {
-        setLoadData(true)
+    const tagName = activePath.split("_")
+    if (tagName[0] !== slugTagName) {
+      return
+    }
+    if (tagName.length === 1) {
+      const elm = document.getElementById(tagName[0])
+      if (elm && !checkElementInViewport(elm, 0)) {
+        scrollToTop(
+          elm.offsetTop + (elm.offsetParent as HTMLElement)?.offsetTop,
+          0
+        )
       }
+    } else if (tagName.length > 1) {
+      setLoadData(true)
     }
   }, [slugTagName, activePath, isBrowser])
 

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

@@ -8,17 +8,20 @@ export const config: DocsConfig = {
   baseUrl,
   basePath: process.env.NEXT_PUBLIC_BASE_PATH,
   // sidebar is auto generated
-  sidebar: {
-    default: [
-      {
-        type: "link",
-        title: "Introduction",
-        path: "introduction",
-        loaded: true,
-      },
-    ],
-    mobile: [],
-  },
+  sidebars: [
+    {
+      sidebar_id: "api-ref",
+      title: "API Reference",
+      items: [
+        {
+          type: "link",
+          title: "Introduction",
+          path: "introduction",
+          loaded: true,
+        },
+      ],
+    },
+  ],
   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/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/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,195 +24,171 @@ 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 = [
   {
-    type: "link",
-    path: "/",
-    title: "Overview",
-  },
-  ...examplesSidebar,
-  {
-    type: "link",
-    path: "/recipes",
-    title: "Recipes",
-    isChildSidebar: true,
-    children: recipesSidebar,
-  },
-  {
-    type: "separator",
-  },
-  {
-    type: "link",
-    path: "/commerce-modules",
-    title: "Commerce Modules",
-    hideChildren: true,
-    sort_sidebar: "alphabetize",
-    children: [
-      ...apiKeySidebar,
-      ...authSidebar,
-      ...cartSidebar,
-      ...currencySidebar,
-      ...customerSidebar,
-      ...fulfillmentSidebar,
-      ...inventorySidebar,
-      ...orderSidebar,
-      ...paymentSidebar,
-      ...pricingSidebar,
-      ...productSidebar,
-      ...promotionSidebar,
-      ...regionSidebar,
-      ...salesChannelSidebar,
-      ...stockLocationSidebar,
-      ...storeSidebar,
-      ...taxSidebar,
-      ...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,
-  },
-  {
-    type: "separator",
-  },
-  {
-    type: "category",
-    title: "SDKs and Tools",
-    children: sdkToolsSidebar,
-  },
-  {
-    type: "category",
-    title: "General",
-    children: [
+    sidebar_id: "resources",
+    title: "Development Resources",
+    items: [
       {
         type: "link",
-        path: "/references/medusa-config",
-        title: "Medusa Configurations",
+        path: "/",
+        title: "Overview",
+      },
+      ...examplesSidebar,
+      ...recipesSidebar,
+      {
+        type: "separator",
       },
       {
         type: "link",
-        path: "/deployment",
-        title: "Deployment Guides",
-        isChildSidebar: true,
+        path: "/commerce-modules",
+        title: "Commerce Modules",
+        hideChildren: true,
+        sort_sidebar: "alphabetize",
+        children: [
+          ...apiKeySidebar,
+          ...authSidebar,
+          ...cartSidebar,
+          ...currencySidebar,
+          ...customerSidebar,
+          ...fulfillmentSidebar,
+          ...inventorySidebar,
+          ...orderSidebar,
+          ...paymentSidebar,
+          ...pricingSidebar,
+          ...productSidebar,
+          ...promotionSidebar,
+          ...regionSidebar,
+          ...salesChannelSidebar,
+          ...stockLocationSidebar,
+          ...storeSidebar,
+          ...taxSidebar,
+          ...userSidebar,
+        ],
+      },
+      ...architecturalModulesSidebar,
+      ...integrationsSidebar,
+      ...pluginsSidebar,
+      ...storefrontGuidesSidebar,
+      {
+        type: "separator",
+      },
+      {
+        type: "category",
+        title: "SDKs and Tools",
+        children: sdkToolsSidebar,
+      },
+      {
+        type: "category",
+        title: "General",
         children: [
           {
-            type: "link",
-            title: "Medusa Cloud",
-            path: "https://medusajs.com/pricing",
-          },
-          {
-            type: "separator",
-          },
-          {
-            type: "category",
-            title: "Self-Hosting",
+            type: "sidebar",
+            sidebar_id: "deployment-guides",
+            title: "Deployment Guides",
             children: [
               {
                 type: "link",
-                path: "https://docs.medusajs.com/learn/deployment/general",
-                title: "General",
+                path: "/deployment",
+                title: "Overview",
+              },
+              {
+                type: "separator",
               },
               {
                 type: "link",
-                path: "/deployment/medusa-application/railway",
-                title: "Railway",
+                title: "Medusa Cloud",
+                path: "https://medusajs.com/pricing",
+              },
+              {
+                type: "separator",
+              },
+              {
+                type: "category",
+                title: "Self-Hosting",
+                children: [
+                  {
+                    type: "link",
+                    path: "https://docs.medusajs.com/learn/deployment/general",
+                    title: "General",
+                  },
+                  {
+                    type: "link",
+                    path: "/deployment/medusa-application/railway",
+                    title: "Railway",
+                  },
+                ],
+              },
+              {
+                type: "category",
+                title: "Next.js Starter",
+                autogenerate_path: "/deployment/storefront",
               },
             ],
           },
-          {
-            type: "category",
-            title: "Next.js Starter",
-            autogenerate_path: "/deployment/storefront",
-          },
+          ...troubleshootingSidebar,
         ],
       },
       {
-        type: "link",
-        path: "/troubleshooting",
-        title: "Troubleshooting Guides",
-        isChildSidebar: true,
-        children: troubleshootingSidebar,
-      },
-    ],
-  },
-  {
-    type: "category",
-    title: "Admin",
-    children: [
-      {
-        type: "link",
-        path: "/admin-widget-injection-zones",
-        title: "Admin Widget Injection Zones",
-      },
-      {
-        type: "link",
-        path: "/admin-components",
-        title: "Admin Components",
-        isChildSidebar: true,
+        type: "category",
+        title: "Admin",
         children: [
           {
-            type: "category",
-            title: "Layouts",
-            autogenerate_path: "/admin-components/layouts",
+            type: "link",
+            path: "/admin-widget-injection-zones",
+            title: "Admin Widget Injection Zones",
           },
           {
-            type: "category",
-            title: "Components",
-            autogenerate_path: "/admin-components/components",
+            type: "sidebar",
+            sidebar_id: "admin-components",
+            title: "Admin Components",
+            children: [
+              {
+                type: "link",
+                path: "/admin-components",
+                title: "Overview",
+              },
+              {
+                type: "separator",
+              },
+              {
+                type: "category",
+                title: "Layouts",
+                autogenerate_path: "/admin-components/layouts",
+              },
+              {
+                type: "category",
+                title: "Components",
+                autogenerate_path: "/admin-components/components",
+              },
+            ],
           },
         ],
       },
-    ],
-  },
-  {
-    type: "category",
-    title: "Lists",
-    children: [
       {
-        type: "link",
-        path: "/medusa-container-resources",
-        title: "Container Dependencies",
+        type: "category",
+        title: "Lists",
+        children: [
+          {
+            type: "link",
+            path: "/medusa-container-resources",
+            title: "Container Dependencies",
+          },
+          {
+            type: "link",
+            path: "/events-reference",
+            title: "Events List",
+          },
+        ],
       },
       {
-        type: "link",
-        path: "/events-reference",
-        title: "Events List",
+        type: "category",
+        title: "References",
+        children: referencesSidebar,
       },
     ],
   },
-  {
-    type: "category",
-    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,161 +1,176 @@
-/** @type {import('types').RawSidebarItem[]} */
+/** @type {import('types').Sidebar.SidebarItem[]} */
 export const architecturalModulesSidebar = [
   {
-    type: "category",
-    title: "Cache Modules",
+    type: "sidebar",
+    sidebar_id: "architectural-modules",
+    title: "Architectural Modules",
     children: [
       {
         type: "link",
-        path: "/architectural-modules/cache",
+        path: "/architectural-modules",
         title: "Overview",
       },
       {
-        type: "link",
-        path: "/architectural-modules/cache/in-memory",
-        title: "In-Memory",
+        type: "separator",
       },
       {
-        type: "link",
-        path: "/architectural-modules/cache/redis",
-        title: "Redis",
-      },
-      {
-        type: "sub-category",
-        title: "Guides",
+        type: "category",
+        title: "Cache Modules",
         children: [
           {
             type: "link",
-            path: "/architectural-modules/cache/create",
-            title: "Create Cache Module",
+            path: "/architectural-modules/cache",
+            title: "Overview",
+          },
+          {
+            type: "link",
+            path: "/architectural-modules/cache/in-memory",
+            title: "In-Memory",
+          },
+          {
+            type: "link",
+            path: "/architectural-modules/cache/redis",
+            title: "Redis",
+          },
+          {
+            type: "sub-category",
+            title: "Guides",
+            children: [
+              {
+                type: "link",
+                path: "/architectural-modules/cache/create",
+                title: "Create Cache Module",
+              },
+            ],
           },
         ],
       },
-    ],
-  },
-  {
-    type: "category",
-    title: "Event Modules",
-    children: [
       {
-        type: "link",
-        path: "/architectural-modules/event",
-        title: "Overview",
-      },
-      {
-        type: "link",
-        path: "/architectural-modules/event/local",
-        title: "Local",
-      },
-      {
-        type: "link",
-        path: "/architectural-modules/event/redis",
-        title: "Redis",
-      },
-      {
-        type: "sub-category",
-        title: "Guides",
+        type: "category",
+        title: "Event Modules",
         children: [
           {
             type: "link",
-            path: "/architectural-modules/event/create",
-            title: "Create Event Module",
+            path: "/architectural-modules/event",
+            title: "Overview",
+          },
+          {
+            type: "link",
+            path: "/architectural-modules/event/local",
+            title: "Local",
+          },
+          {
+            type: "link",
+            path: "/architectural-modules/event/redis",
+            title: "Redis",
+          },
+          {
+            type: "sub-category",
+            title: "Guides",
+            children: [
+              {
+                type: "link",
+                path: "/architectural-modules/event/create",
+                title: "Create Event Module",
+              },
+            ],
           },
         ],
       },
-    ],
-  },
-  {
-    type: "category",
-    title: "File Module Providers",
-    children: [
       {
-        type: "link",
-        path: "/architectural-modules/file",
-        title: "Overview",
-      },
-      {
-        type: "link",
-        path: "/architectural-modules/file/local",
-        title: "Local",
-      },
-      {
-        type: "link",
-        path: "/architectural-modules/file/s3",
-        title: "AWS S3 (and Compatible APIs)",
-      },
-      {
-        type: "sub-category",
-        title: "Guides",
+        type: "category",
+        title: "File Module Providers",
         children: [
           {
             type: "link",
-            path: "/references/file-provider-module",
-            title: "Create File Provider",
+            path: "/architectural-modules/file",
+            title: "Overview",
+          },
+          {
+            type: "link",
+            path: "/architectural-modules/file/local",
+            title: "Local",
+          },
+          {
+            type: "link",
+            path: "/architectural-modules/file/s3",
+            title: "AWS S3 (and Compatible APIs)",
+          },
+          {
+            type: "sub-category",
+            title: "Guides",
+            children: [
+              {
+                type: "link",
+                path: "/references/file-provider-module",
+                title: "Create File Provider",
+              },
+            ],
           },
         ],
       },
-    ],
-  },
-  {
-    type: "category",
-    title: "Notification Module Providers",
-    children: [
       {
-        type: "link",
-        path: "/architectural-modules/notification",
-        title: "Overview",
-      },
-      {
-        type: "link",
-        path: "/architectural-modules/notification/local",
-        title: "Local",
-      },
-      {
-        type: "link",
-        path: "/architectural-modules/notification/sendgrid",
-        title: "SendGrid",
-      },
-      {
-        type: "sub-category",
-        title: "Guides",
+        type: "category",
+        title: "Notification Module Providers",
         children: [
           {
             type: "link",
-            path: "/references/notification-provider-module",
-            title: "Create Notification Provider",
+            path: "/architectural-modules/notification",
+            title: "Overview",
           },
           {
             type: "link",
-            path: "/integrations/guides/resend",
-            title: "Integrate Resend",
+            path: "/architectural-modules/notification/local",
+            title: "Local",
           },
           {
             type: "link",
-            path: "/architectural-modules/notification/send-notification",
-            title: "Send Notification",
+            path: "/architectural-modules/notification/sendgrid",
+            title: "SendGrid",
+          },
+          {
+            type: "sub-category",
+            title: "Guides",
+            children: [
+              {
+                type: "link",
+                path: "/references/notification-provider-module",
+                title: "Create Notification Provider",
+              },
+              {
+                type: "link",
+                path: "/integrations/guides/resend",
+                title: "Integrate Resend",
+              },
+              {
+                type: "link",
+                path: "/architectural-modules/notification/send-notification",
+                title: "Send Notification",
+              },
+            ],
           },
         ],
       },
-    ],
-  },
-  {
-    type: "category",
-    title: "Workflow Engine Modules",
-    children: [
       {
-        type: "link",
-        path: "/architectural-modules/workflow-engine",
-        title: "Overview",
-      },
-      {
-        type: "link",
-        path: "/architectural-modules/workflow-engine/in-memory",
-        title: "In-Memory",
-      },
-      {
-        type: "link",
-        path: "/architectural-modules/workflow-engine/redis",
-        title: "Redis",
+        type: "category",
+        title: "Workflow Engine Modules",
+        children: [
+          {
+            type: "link",
+            path: "/architectural-modules/workflow-engine",
+            title: "Overview",
+          },
+          {
+            type: "link",
+            path: "/architectural-modules/workflow-engine/in-memory",
+            title: "In-Memory",
+          },
+          {
+            type: "link",
+            path: "/architectural-modules/workflow-engine/redis",
+            title: "Redis",
+          },
+        ],
       },
     ],
   },

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,78 +1,93 @@
-/** @type {import('types').RawSidebarItem[]} */
+/** @type {import('types').Sidebar.SidebarItem[]} */
 export const integrationsSidebar = [
   {
-    type: "category",
-    title: "Auth",
+    type: "sidebar",
+    sidebar_id: "integrations",
+    title: "Integrations",
     children: [
       {
         type: "link",
-        path: "/commerce-modules/auth/auth-providers/google",
-        title: "Google",
+        path: "/integrations",
+        title: "Overview",
       },
       {
-        type: "link",
-        path: "/commerce-modules/auth/auth-providers/github",
-        title: "GitHub",
-      },
-    ],
-  },
-  {
-    type: "category",
-    title: "CMS",
-    children: [
-      {
-        type: "link",
-        path: "/integrations/guides/sanity",
-        title: "Sanity",
-      },
-    ],
-  },
-  {
-    type: "category",
-    title: "File",
-    children: [
-      {
-        type: "link",
-        path: "/architectural-modules/file/s3",
-        title: "AWS",
-      },
-    ],
-  },
-  {
-    type: "category",
-    title: "Fulfillment",
-    children: [
-      {
-        type: "link",
-        path: "/integrations/guides/shipstation",
-        title: "ShipStation",
-      },
-    ],
-  },
-  {
-    type: "category",
-    title: "Notification",
-    children: [
-      {
-        type: "link",
-        path: "/architectural-modules/notification/sendgrid",
-        title: "SendGrid",
+        type: "separator",
       },
       {
-        type: "link",
-        path: "/integrations/guides/resend",
-        title: "Resend",
+        type: "category",
+        title: "Auth",
+        children: [
+          {
+            type: "link",
+            path: "/commerce-modules/auth/auth-providers/google",
+            title: "Google",
+          },
+          {
+            type: "link",
+            path: "/commerce-modules/auth/auth-providers/github",
+            title: "GitHub",
+          },
+        ],
       },
-    ],
-  },
-  {
-    type: "category",
-    title: "Payment",
-    children: [
       {
-        type: "link",
-        path: "/commerce-modules/payment/payment-provider/stripe",
-        title: "Stripe",
+        type: "category",
+        title: "CMS",
+        children: [
+          {
+            type: "link",
+            path: "/integrations/guides/sanity",
+            title: "Sanity",
+          },
+        ],
+      },
+      {
+        type: "category",
+        title: "File",
+        children: [
+          {
+            type: "link",
+            path: "/architectural-modules/file/s3",
+            title: "AWS",
+          },
+        ],
+      },
+      {
+        type: "category",
+        title: "Fulfillment",
+        children: [
+          {
+            type: "link",
+            path: "/integrations/guides/shipstation",
+            title: "ShipStation",
+          },
+        ],
+      },
+      {
+        type: "category",
+        title: "Notification",
+        children: [
+          {
+            type: "link",
+            path: "/architectural-modules/notification/sendgrid",
+            title: "SendGrid",
+          },
+          {
+            type: "link",
+            path: "/integrations/guides/resend",
+            title: "Resend",
+          },
+        ],
+      },
+      {
+        type: "category",
+        title: "Payment",
+        children: [
+          {
+            type: "link",
+            path: "/commerce-modules/payment/payment-provider/stripe",
+            title: "Stripe",
+          },
+        ],
       },
     ],
   },

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,19 +1,26 @@
-/** @type {import('types').RawSidebarItem[]} */
+/** @type {import('types').Sidebar.SidebarItem[]} */
 export const pluginsSidebar = [
   {
-    type: "link",
-    title: "Overview",
-    path: "/plugins",
-  },
-  {
-    type: "category",
-    title: "Guides",
+    type: "sidebar",
+    sidebar_id: "plugins",
+    title: "Plugins",
     children: [
       {
         type: "link",
-        title: "Wishlist",
-        path: "/plugins/guides/wishlist",
-        description: "Learn how to build a wishlist plugin.",
+        title: "Overview",
+        path: "/plugins",
+      },
+      {
+        type: "category",
+        title: "Guides",
+        children: [
+          {
+            type: "link",
+            title: "Wishlist",
+            path: "/plugins/guides/wishlist",
+            description: "Learn how to build a wishlist plugin.",
+          },
+        ],
       },
     ],
   },

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,103 +1,118 @@
-/** @type {import('types').RawSidebarItem[]} */
+/** @type {import('types').Sidebar.SidebarItem[]} */
 export const recipesSidebar = [
   {
-    type: "link",
-    path: "/recipes/marketplace",
-    title: "Marketplace",
+    type: "sidebar",
+    sidebar_id: "recipes",
+    title: "Recipes",
     children: [
       {
         type: "link",
-        path: "/recipes/marketplace/examples/vendors",
-        title: "Example: Vendors",
+        path: "/recipes",
+        title: "Overview",
+      },
+      {
+        type: "separator",
       },
       {
         type: "link",
-        path: "/recipes/marketplace/examples/restaurant-delivery",
-        title: "Example: Restaurant-Delivery",
+        path: "/recipes/marketplace",
+        title: "Marketplace",
+        children: [
+          {
+            type: "link",
+            path: "/recipes/marketplace/examples/vendors",
+            title: "Example: Vendors",
+          },
+          {
+            type: "link",
+            path: "/recipes/marketplace/examples/restaurant-delivery",
+            title: "Example: Restaurant-Delivery",
+          },
+        ],
       },
-    ],
-  },
-  {
-    type: "link",
-    path: "/recipes/subscriptions",
-    title: "Subscriptions",
-    children: [
       {
         type: "link",
-        path: "/recipes/subscriptions/examples/standard",
-        title: "Example",
+        path: "/recipes/subscriptions",
+        title: "Subscriptions",
+        children: [
+          {
+            type: "link",
+            path: "/recipes/subscriptions/examples/standard",
+            title: "Example",
+          },
+        ],
       },
-    ],
-  },
-  {
-    type: "link",
-    path: "/recipes/digital-products",
-    title: "Digital Products",
-    children: [
       {
         type: "link",
-        path: "/recipes/digital-products/examples/standard",
-        title: "Example",
+        path: "/recipes/digital-products",
+        title: "Digital Products",
+        children: [
+          {
+            type: "link",
+            path: "/recipes/digital-products/examples/standard",
+            title: "Example",
+          },
+        ],
       },
-    ],
-  },
-  {
-    type: "link",
-    path: "/recipes/erp",
-    title: "Integrate ERP",
-    children: [
       {
         type: "link",
-        path: "/recipes/erp/odoo",
-        title: "Example: Odoo Integration",
+        path: "/recipes/erp",
+        title: "Integrate ERP",
+        children: [
+          {
+            type: "link",
+            path: "/recipes/erp/odoo",
+            title: "Example: Odoo Integration",
+          },
+        ],
       },
-    ],
-  },
-  {
-    type: "link",
-    path: "/recipes/b2b",
-    title: "B2B",
-  },
-  {
-    type: "link",
-    path: "/recipes/commerce-automation",
-    title: "Commerce Automation",
-    children: [
       {
         type: "link",
-        path: "/recipes/commerce-automation/restock-notification",
-        title: "Example: Restock Notifications",
+        path: "/recipes/b2b",
+        title: "B2B",
+      },
+      {
+        type: "link",
+        path: "/recipes/commerce-automation",
+        title: "Commerce Automation",
+        children: [
+          {
+            type: "link",
+            path: "/recipes/commerce-automation/restock-notification",
+            title: "Example: Restock Notifications",
+          },
+        ],
+      },
+      {
+        type: "link",
+        path: "/recipes/ecommerce",
+        title: "Ecommerce",
+      },
+      {
+        type: "link",
+        path: "/recipes/multi-region-store",
+        title: "Multi-Region Store",
+      },
+      {
+        type: "link",
+        path: "/recipes/omnichannel",
+        title: "Omnichannel Store",
+      },
+      {
+        type: "link",
+        path: "/recipes/oms",
+        title: "OMS",
+      },
+      {
+        type: "link",
+        path: "/recipes/personalized-products",
+        title: "Personalized Products",
+      },
+      {
+        type: "link",
+        path: "/recipes/pos",
+        title: "POS",
       },
     ],
   },
-  {
-    type: "link",
-    path: "/recipes/ecommerce",
-    title: "Ecommerce",
-  },
-  {
-    type: "link",
-    path: "/recipes/multi-region-store",
-    title: "Multi-Region Store",
-  },
-  {
-    type: "link",
-    path: "/recipes/omnichannel",
-    title: "Omnichannel Store",
-  },
-  {
-    type: "link",
-    path: "/recipes/oms",
-    title: "OMS",
-  },
-  {
-    type: "link",
-    path: "/recipes/personalized-products",
-    title: "Personalized Products",
-  },
-  {
-    type: "link",
-    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: "link",
-    path: "/references/workflows",
+    type: "sidebar",
+    sidebar_id: "workflows-sdk-reference",
     title: "Workflows SDK",
     childSidebarTitle: "Workflows SDK Reference",
-    isChildSidebar: true,
     children: [
+      {
+        type: "link",
+        path: "/references/workflows",
+        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",
@@ -53,11 +67,18 @@ export const referencesSidebar = [
     ],
   },
   {
-    type: "link",
-    path: "/service-factory-reference",
+    type: "sidebar",
+    sidebar_id: "service-factory-reference",
     title: "Service Factory",
-    isChildSidebar: true,
     children: [
+      {
+        type: "link",
+        path: "/service-factory-reference",
+        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: "link",
+    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,259 +1,274 @@
-/** @type {import('types').RawSidebarItem[]} */
+/** @type {import('types').Sidebar.SidebarItem[]} */
 export const storefrontGuidesSidebar = [
   {
-    type: "category",
-    title: "General",
+    type: "sidebar",
+    sidebar_id: "storefront-development",
+    title: "Storefront Development",
     children: [
       {
         type: "link",
-        path: "/storefront-development/tips",
-        title: "Tips",
-      },
-      {
-        type: "link",
-        path: "/storefront-development/publishable-api-keys",
-        title: "Publishable API Key",
-      },
-    ],
-  },
-  {
-    type: "category",
-    title: "Examples",
-    children: [
-      {
-        type: "link",
-        path: "/storefront-development/guides/express-checkout",
-        title: "Express Checkout Storefront",
-      },
-    ],
-  },
-  {
-    type: "category",
-    title: "Regions",
-    children: [
-      {
-        type: "link",
-        path: "/storefront-development/regions",
+        path: "/storefront-development",
         title: "Overview",
       },
       {
-        type: "link",
-        path: "/storefront-development/regions/list",
-        title: "List Regions",
+        type: "separator",
       },
       {
-        type: "link",
-        path: "/storefront-development/regions/store-retrieve-region",
-        title: "Store and Retrieve Regions",
-      },
-      {
-        type: "link",
-        path: "/storefront-development/regions/context",
-        title: "Region React Context",
-      },
-    ],
-  },
-  {
-    type: "category",
-    title: "Products",
-    children: [
-      {
-        type: "link",
-        path: "/storefront-development/products/list",
-        title: "List Products",
-      },
-      {
-        type: "link",
-        path: "/storefront-development/products/retrieve",
-        title: "Retrieve a Product",
-      },
-      {
-        type: "link",
-        path: "/storefront-development/products/variants",
-        title: "Select a Variant",
-      },
-      {
-        type: "link",
-        path: "/storefront-development/products/price",
-        title: "Retrieve Variant Prices",
-        autogenerate_path: "storefront-development/products/price/examples",
-      },
-      {
-        type: "link",
-        path: "/storefront-development/products/inventory",
-        title: "Retrieve Variant Inventory",
-      },
-    ],
-  },
-  {
-    type: "category",
-    title: "Product Categories",
-    children: [
-      {
-        type: "link",
-        path: "/storefront-development/products/categories/list",
-        title: "List Categories",
-      },
-      {
-        type: "link",
-        path: "/storefront-development/products/categories/retrieve",
-        title: "Retrieve a Category",
-      },
-      {
-        type: "link",
-        path: "/storefront-development/products/categories/products",
-        title: "Retrieve a Category's Products",
-      },
-      {
-        type: "link",
-        path: "/storefront-development/products/categories/nested-categories",
-        title: "Retrieve Nested Categories",
-      },
-    ],
-  },
-  {
-    type: "category",
-    title: "Product Collections",
-    children: [
-      {
-        type: "link",
-        path: "/storefront-development/products/collections/list",
-        title: "List Collections",
-      },
-      {
-        type: "link",
-        path: "/storefront-development/products/collections/retrieve",
-        title: "Retrieve a Collection",
-      },
-      {
-        type: "link",
-        path: "/storefront-development/products/collections/products",
-        title: "Retrieve a Collection's Products",
-      },
-    ],
-  },
-  {
-    type: "category",
-    title: "Carts",
-    children: [
-      {
-        type: "link",
-        path: "/storefront-development/cart/create",
-        title: "Create Cart",
-      },
-      {
-        type: "link",
-        path: "/storefront-development/cart/retrieve",
-        title: "Retrieve Cart",
-      },
-      {
-        type: "link",
-        path: "/storefront-development/cart/context",
-        title: "Cart React Context",
-      },
-      {
-        type: "link",
-        path: "/storefront-development/cart/update",
-        title: "Update Cart",
-      },
-      {
-        type: "link",
-        path: "/storefront-development/cart/manage-items",
-        title: "Manage Line Items",
-      },
-    ],
-  },
-  {
-    type: "category",
-    title: "Checkout",
-    children: [
-      {
-        type: "link",
-        path: "/storefront-development/checkout",
-        title: "Overview",
-      },
-      {
-        type: "link",
-        path: "/storefront-development/checkout/email",
-        title: "1. Enter Email",
-      },
-      {
-        type: "link",
-        path: "/storefront-development/checkout/address",
-        title: "2. Set Address",
-      },
-      {
-        type: "link",
-        path: "/storefront-development/checkout/shipping",
-        title: "3. Choose Shipping Method",
-      },
-      {
-        type: "link",
-        path: "/storefront-development/checkout/payment",
-        title: "4. Choose Payment Provider",
+        type: "category",
+        title: "General",
         children: [
           {
             type: "link",
-            path: "/storefront-development/checkout/payment/stripe",
-            title: "Example: Stripe",
+            path: "/storefront-development/tips",
+            title: "Tips",
+          },
+          {
+            type: "link",
+            path: "/storefront-development/publishable-api-keys",
+            title: "Publishable API Key",
           },
         ],
       },
       {
-        type: "link",
-        path: "/storefront-development/checkout/complete-cart",
-        title: "5. Complete Cart",
-      },
-    ],
-  },
-  {
-    type: "category",
-    title: "Customers",
-    children: [
-      {
-        type: "link",
-        path: "/storefront-development/customers/register",
-        title: "Register Customer",
+        type: "category",
+        title: "Examples",
+        children: [
+          {
+            type: "link",
+            path: "/storefront-development/guides/express-checkout",
+            title: "Express Checkout Storefront",
+          },
+        ],
       },
       {
-        type: "link",
-        path: "/storefront-development/customers/login",
-        title: "Login Customer",
+        type: "category",
+        title: "Regions",
+        children: [
+          {
+            type: "link",
+            path: "/storefront-development/regions",
+            title: "Overview",
+          },
+          {
+            type: "link",
+            path: "/storefront-development/regions/list",
+            title: "List Regions",
+          },
+          {
+            type: "link",
+            path: "/storefront-development/regions/store-retrieve-region",
+            title: "Store and Retrieve Regions",
+          },
+          {
+            type: "link",
+            path: "/storefront-development/regions/context",
+            title: "Region React Context",
+          },
+        ],
       },
       {
-        type: "link",
-        path: "/storefront-development/customers/third-party-login",
-        title: "Third-Party (Social) Login",
+        type: "category",
+        title: "Products",
+        children: [
+          {
+            type: "link",
+            path: "/storefront-development/products/list",
+            title: "List Products",
+          },
+          {
+            type: "link",
+            path: "/storefront-development/products/retrieve",
+            title: "Retrieve a Product",
+          },
+          {
+            type: "link",
+            path: "/storefront-development/products/variants",
+            title: "Select a Variant",
+          },
+          {
+            type: "link",
+            path: "/storefront-development/products/price",
+            title: "Retrieve Variant Prices",
+            autogenerate_path: "storefront-development/products/price/examples",
+          },
+          {
+            type: "link",
+            path: "/storefront-development/products/inventory",
+            title: "Retrieve Variant Inventory",
+          },
+        ],
       },
       {
-        type: "link",
-        path: "/storefront-development/customers/reset-password",
-        title: "Reset Password",
+        type: "category",
+        title: "Product Categories",
+        children: [
+          {
+            type: "link",
+            path: "/storefront-development/products/categories/list",
+            title: "List Categories",
+          },
+          {
+            type: "link",
+            path: "/storefront-development/products/categories/retrieve",
+            title: "Retrieve a Category",
+          },
+          {
+            type: "link",
+            path: "/storefront-development/products/categories/products",
+            title: "Retrieve a Category's Products",
+          },
+          {
+            type: "link",
+            path: "/storefront-development/products/categories/nested-categories",
+            title: "Retrieve Nested Categories",
+          },
+        ],
       },
       {
-        type: "link",
-        path: "/storefront-development/customers/retrieve",
-        title: "Retrieve Customer",
+        type: "category",
+        title: "Product Collections",
+        children: [
+          {
+            type: "link",
+            path: "/storefront-development/products/collections/list",
+            title: "List Collections",
+          },
+          {
+            type: "link",
+            path: "/storefront-development/products/collections/retrieve",
+            title: "Retrieve a Collection",
+          },
+          {
+            type: "link",
+            path: "/storefront-development/products/collections/products",
+            title: "Retrieve a Collection's Products",
+          },
+        ],
       },
       {
-        type: "link",
-        path: "/storefront-development/customers/context",
-        title: "Customer React Context",
+        type: "category",
+        title: "Carts",
+        children: [
+          {
+            type: "link",
+            path: "/storefront-development/cart/create",
+            title: "Create Cart",
+          },
+          {
+            type: "link",
+            path: "/storefront-development/cart/retrieve",
+            title: "Retrieve Cart",
+          },
+          {
+            type: "link",
+            path: "/storefront-development/cart/context",
+            title: "Cart React Context",
+          },
+          {
+            type: "link",
+            path: "/storefront-development/cart/update",
+            title: "Update Cart",
+          },
+          {
+            type: "link",
+            path: "/storefront-development/cart/manage-items",
+            title: "Manage Line Items",
+          },
+        ],
       },
       {
-        type: "link",
-        path: "/storefront-development/customers/profile",
-        title: "Edit Customer Profile",
+        type: "category",
+        title: "Checkout",
+        children: [
+          {
+            type: "link",
+            path: "/storefront-development/checkout",
+            title: "Overview",
+          },
+          {
+            type: "link",
+            path: "/storefront-development/checkout/email",
+            title: "1. Enter Email",
+          },
+          {
+            type: "link",
+            path: "/storefront-development/checkout/address",
+            title: "2. Set Address",
+          },
+          {
+            type: "link",
+            path: "/storefront-development/checkout/shipping",
+            title: "3. Choose Shipping Method",
+          },
+          {
+            type: "link",
+            path: "/storefront-development/checkout/payment",
+            title: "4. Choose Payment Provider",
+            children: [
+              {
+                type: "link",
+                path: "/storefront-development/checkout/payment/stripe",
+                title: "Example: Stripe",
+              },
+            ],
+          },
+          {
+            type: "link",
+            path: "/storefront-development/checkout/complete-cart",
+            title: "5. Complete Cart",
+          },
+        ],
       },
       {
-        type: "link",
-        path: "/storefront-development/customers/addresses",
-        title: "Manage Customer Addresses",
-      },
-      {
-        type: "link",
-        path: "/storefront-development/customers/log-out",
-        title: "Log-out Customer",
+        type: "category",
+        title: "Customers",
+        children: [
+          {
+            type: "link",
+            path: "/storefront-development/customers/register",
+            title: "Register Customer",
+          },
+          {
+            type: "link",
+            path: "/storefront-development/customers/login",
+            title: "Login Customer",
+          },
+          {
+            type: "link",
+            path: "/storefront-development/customers/third-party-login",
+            title: "Third-Party (Social) Login",
+          },
+          {
+            type: "link",
+            path: "/storefront-development/customers/reset-password",
+            title: "Reset Password",
+          },
+          {
+            type: "link",
+            path: "/storefront-development/customers/retrieve",
+            title: "Retrieve Customer",
+          },
+          {
+            type: "link",
+            path: "/storefront-development/customers/context",
+            title: "Customer React Context",
+          },
+          {
+            type: "link",
+            path: "/storefront-development/customers/profile",
+            title: "Edit Customer Profile",
+          },
+          {
+            type: "link",
+            path: "/storefront-development/customers/addresses",
+            title: "Manage Customer Addresses",
+          },
+          {
+            type: "link",
+            path: "/storefront-development/customers/log-out",
+            title: "Log-out Customer",
+          },
+        ],
       },
     ],
   },

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,99 +1,114 @@
-/** @type {import('types').RawSidebarItem[]} */
+/** @type {import('types').Sidebar.SidebarItem[]} */
 export const troubleshootingSidebar = [
   {
-    type: "category",
-    title: "Installation",
+    type: "sidebar",
+    sidebar_id: "troubleshooting",
+    title: "Troubleshooting",
     children: [
       {
         type: "link",
-        path: "/troubleshooting/create-medusa-app-errors",
-        title: "Create Medusa App Errors",
+        path: "/troubleshooting",
+        title: "Overview",
       },
       {
-        type: "link",
-        path: "/troubleshooting/errors-installing-cli",
-        title: "Errors Installing CLI",
+        type: "separator",
       },
       {
-        type: "link",
-        path: "/troubleshooting/general-errors",
-        title: "General Errors",
-      },
-    ],
-  },
-  {
-    type: "category",
-    title: "Medusa Application",
-    children: [
-      {
-        type: "link",
-        path: "/troubleshooting/eaddrinuse",
-        title: "EADDRINUSE Error",
+        type: "category",
+        title: "Installation",
+        children: [
+          {
+            type: "link",
+            path: "/troubleshooting/create-medusa-app-errors",
+            title: "Create Medusa App Errors",
+          },
+          {
+            type: "link",
+            path: "/troubleshooting/errors-installing-cli",
+            title: "Errors Installing CLI",
+          },
+          {
+            type: "link",
+            path: "/troubleshooting/general-errors",
+            title: "General Errors",
+          },
+        ],
       },
       {
-        type: "link",
-        path: "/troubleshooting/database-errors",
-        title: "Database Errors",
+        type: "category",
+        title: "Medusa Application",
+        children: [
+          {
+            type: "link",
+            path: "/troubleshooting/eaddrinuse",
+            title: "EADDRINUSE Error",
+          },
+          {
+            type: "link",
+            path: "/troubleshooting/database-errors",
+            title: "Database Errors",
+          },
+          {
+            type: "link",
+            path: "/troubleshooting/dist-imports",
+            title: "Importing from /dist",
+          },
+          {
+            type: "link",
+            path: "/troubleshooting/workflow-errors",
+            title: "Workflow Errors",
+          },
+          {
+            type: "link",
+            path: "/troubleshooting/test-errors",
+            title: "Test Errors",
+          },
+        ],
       },
       {
-        type: "link",
-        path: "/troubleshooting/dist-imports",
-        title: "Importing from /dist",
+        type: "category",
+        title: "Admin Development",
+        children: [
+          {
+            type: "link",
+            path: "/troubleshooting/medusa-admin/no-widget-route",
+            title: "Widget or Route not Showing",
+          },
+        ],
       },
       {
-        type: "link",
-        path: "/troubleshooting/workflow-errors",
-        title: "Workflow Errors",
+        type: "category",
+        title: "Upgrade",
+        children: [
+          {
+            type: "link",
+            path: "/troubleshooting/errors-after-upgrading",
+            title: "Errors After Upgrading",
+          },
+        ],
       },
       {
-        type: "link",
-        path: "/troubleshooting/test-errors",
-        title: "Test Errors",
+        type: "category",
+        title: "Frontend",
+        children: [
+          {
+            type: "link",
+            path: "/troubleshooting/cors-errors",
+            title: "CORS Errors",
+          },
+        ],
       },
-    ],
-  },
-  {
-    type: "category",
-    title: "Admin Development",
-    children: [
       {
-        type: "link",
-        path: "/troubleshooting/medusa-admin/no-widget-route",
-        title: "Widget or Route not Showing",
-      },
-    ],
-  },
-  {
-    type: "category",
-    title: "Upgrade",
-    children: [
-      {
-        type: "link",
-        path: "/troubleshooting/errors-after-upgrading",
-        title: "Errors After Upgrading",
-      },
-    ],
-  },
-  {
-    type: "category",
-    title: "Frontend",
-    children: [
-      {
-        type: "link",
-        path: "/troubleshooting/cors-errors",
-        title: "CORS Errors",
-      },
-    ],
-  },
-  {
-    type: "category",
-    title: "Integrations",
-    hasTitleStyling: true,
-    children: [
-      {
-        type: "link",
-        path: "/troubleshooting/s3",
-        title: "S3 Module Provider Errors",
+        type: "category",
+        title: "Integrations",
+        hasTitleStyling: true,
+        children: [
+          {
+            type: "link",
+            path: "/troubleshooting/s3",
+            title: "S3 Module Provider Errors",
+          },
+        ],
       },
     ],
   },

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,166 +1,59 @@
-export const generatedSidebar = [
+export const generatedSidebars = [
   {
-    "loaded": true,
-    "isPathHref": true,
-    "type": "link",
-    "path": "/",
-    "title": "Introduction",
-    "children": []
-  },
-  {
-    "loaded": true,
-    "isPathHref": true,
-    "type": "link",
-    "path": "/reset-password",
-    "title": "Reset Password",
-    "children": []
-  },
-  {
-    "type": "separator"
-  },
-  {
-    "loaded": true,
-    "isPathHref": true,
-    "type": "category",
-    "title": "Tips",
-    "autogenerate_path": "/tips",
-    "children": [
+    "sidebar_id": "user-guide",
+    "title": "User Guide",
+    "items": [
       {
         "loaded": true,
         "isPathHref": true,
         "type": "link",
-        "path": "/tips/bulk-editor",
-        "title": "Bulk Editor in Medusa Admin",
-        "description": "",
+        "path": "/",
+        "title": "Introduction",
         "children": []
       },
       {
         "loaded": true,
         "isPathHref": true,
         "type": "link",
-        "path": "/tips/languages",
-        "title": "Languages in Medusa Admin",
-        "description": "",
+        "path": "/reset-password",
+        "title": "Reset Password",
         "children": []
       },
+      {
+        "type": "separator"
+      },
       {
         "loaded": true,
         "isPathHref": true,
-        "type": "link",
-        "path": "/tips/lists",
-        "title": "Lists",
-        "description": "",
-        "children": []
-      }
-    ]
-  },
-  {
-    "loaded": true,
-    "isPathHref": true,
-    "type": "category",
-    "title": "Orders",
-    "children": [
-      {
-        "loaded": true,
-        "isPathHref": true,
-        "type": "link",
-        "title": "Overview",
-        "path": "/orders",
-        "children": []
-      },
-      {
-        "loaded": true,
-        "isPathHref": true,
-        "type": "link",
-        "title": "Manage Details",
-        "path": "/orders/manage",
-        "children": []
-      },
-      {
-        "loaded": true,
-        "isPathHref": true,
-        "type": "link",
-        "title": "Manage Payments",
-        "path": "/orders/payments",
-        "children": []
-      },
-      {
-        "loaded": true,
-        "isPathHref": true,
-        "type": "link",
-        "title": "Manage Fulfillments",
-        "path": "/orders/fulfillments",
-        "children": []
-      },
-      {
-        "loaded": true,
-        "isPathHref": true,
-        "type": "link",
-        "title": "Edit Order Items",
-        "path": "/orders/edit",
-        "children": []
-      },
-      {
-        "loaded": true,
-        "isPathHref": true,
-        "type": "link",
-        "title": "Manage Returns",
-        "path": "/orders/returns",
-        "children": []
-      },
-      {
-        "loaded": true,
-        "isPathHref": true,
-        "type": "link",
-        "title": "Manage Exchanges",
-        "path": "/orders/exchanges",
-        "children": []
-      },
-      {
-        "loaded": true,
-        "isPathHref": true,
-        "type": "link",
-        "title": "Manage Claims",
-        "path": "/orders/claims",
-        "children": []
-      }
-    ]
-  },
-  {
-    "loaded": true,
-    "isPathHref": true,
-    "type": "category",
-    "title": "Products",
-    "children": [
-      {
-        "loaded": true,
-        "isPathHref": true,
-        "type": "link",
-        "title": "Overview",
-        "path": "/products",
-        "children": []
-      },
-      {
-        "loaded": true,
-        "isPathHref": true,
-        "type": "link",
-        "title": "Create Product",
-        "path": "/products/create",
+        "type": "category",
+        "title": "Tips",
+        "autogenerate_path": "/tips",
         "children": [
           {
             "loaded": true,
             "isPathHref": true,
             "type": "link",
-            "title": "Multi-Part Product",
-            "path": "/products/create/multi-part",
+            "path": "/tips/bulk-editor",
+            "title": "Bulk Editor in Medusa Admin",
+            "description": "",
             "children": []
           },
           {
             "loaded": true,
             "isPathHref": true,
             "type": "link",
-            "title": "Bundle Product",
-            "path": "/products/create/bundle",
+            "path": "/tips/languages",
+            "title": "Languages in Medusa Admin",
+            "description": "",
+            "children": []
+          },
+          {
+            "loaded": true,
+            "isPathHref": true,
+            "type": "link",
+            "path": "/tips/lists",
+            "title": "Lists",
+            "description": "",
             "children": []
           }
         ]
@@ -168,224 +61,71 @@ export const generatedSidebar = [
       {
         "loaded": true,
         "isPathHref": true,
-        "type": "link",
-        "title": "Edit Product",
-        "path": "/products/edit",
-        "children": []
-      },
-      {
-        "loaded": true,
-        "isPathHref": true,
-        "type": "link",
-        "title": "Manage Variants",
-        "path": "/products/variants",
-        "children": []
-      },
-      {
-        "loaded": true,
-        "isPathHref": true,
-        "type": "link",
-        "title": "Manage Collections",
-        "path": "/products/collections",
-        "children": []
-      },
-      {
-        "loaded": true,
-        "isPathHref": true,
-        "type": "link",
-        "title": "Manage Categories",
-        "path": "/products/categories",
-        "children": []
-      },
-      {
-        "loaded": true,
-        "isPathHref": true,
-        "type": "link",
-        "title": "Import Products",
-        "path": "/products/import",
-        "children": []
-      },
-      {
-        "loaded": true,
-        "isPathHref": true,
-        "type": "link",
-        "title": "Export Products",
-        "path": "/products/export",
-        "children": []
-      }
-    ]
-  },
-  {
-    "loaded": true,
-    "isPathHref": true,
-    "type": "category",
-    "title": "Inventory",
-    "children": [
-      {
-        "loaded": true,
-        "isPathHref": true,
-        "type": "link",
-        "title": "Overview",
-        "path": "/inventory",
-        "children": []
-      },
-      {
-        "loaded": true,
-        "isPathHref": true,
-        "type": "link",
-        "title": "Manage Inventory",
-        "path": "/inventory/inventory",
-        "children": []
-      },
-      {
-        "loaded": true,
-        "isPathHref": true,
-        "type": "link",
-        "title": "Manage Reservations",
-        "path": "/inventory/reservations",
-        "children": []
-      }
-    ]
-  },
-  {
-    "loaded": true,
-    "isPathHref": true,
-    "type": "category",
-    "title": "Customers",
-    "children": [
-      {
-        "loaded": true,
-        "isPathHref": true,
-        "type": "link",
-        "title": "Overview",
-        "path": "/customers",
-        "children": []
-      },
-      {
-        "loaded": true,
-        "isPathHref": true,
-        "type": "link",
-        "title": "Manage Customers",
-        "path": "/customers/manage",
-        "children": []
-      },
-      {
-        "loaded": true,
-        "isPathHref": true,
-        "type": "link",
-        "title": "Manage Groups",
-        "path": "/customers/groups",
-        "children": []
-      }
-    ]
-  },
-  {
-    "loaded": true,
-    "isPathHref": true,
-    "type": "category",
-    "title": "Promotions",
-    "children": [
-      {
-        "loaded": true,
-        "isPathHref": true,
-        "type": "link",
-        "title": "Overview",
-        "path": "/promotions",
-        "children": []
-      },
-      {
-        "loaded": true,
-        "isPathHref": true,
-        "type": "link",
-        "title": "Create Promotion",
-        "path": "/promotions/create",
-        "children": []
-      },
-      {
-        "loaded": true,
-        "isPathHref": true,
-        "type": "link",
-        "title": "Manage Promotion",
-        "path": "/promotions/manage",
-        "children": []
-      },
-      {
-        "loaded": true,
-        "isPathHref": true,
-        "type": "link",
-        "title": "Manage Campaigns",
-        "path": "/promotions/campaigns",
-        "children": []
-      }
-    ]
-  },
-  {
-    "loaded": true,
-    "isPathHref": true,
-    "type": "category",
-    "title": "Price Lists",
-    "children": [
-      {
-        "loaded": true,
-        "isPathHref": true,
-        "type": "link",
-        "title": "Overview",
-        "path": "/price-lists",
-        "children": []
-      },
-      {
-        "loaded": true,
-        "isPathHref": true,
-        "type": "link",
-        "title": "Create Price List",
-        "path": "/price-lists/create",
-        "children": []
-      },
-      {
-        "loaded": true,
-        "isPathHref": true,
-        "type": "link",
-        "title": "Manage Price List",
-        "path": "/price-lists/manage",
-        "children": []
-      }
-    ]
-  },
-  {
-    "loaded": true,
-    "isPathHref": true,
-    "type": "category",
-    "title": "Settings",
-    "children": [
-      {
-        "loaded": true,
-        "isPathHref": true,
-        "type": "link",
-        "title": "Overview",
-        "path": "/settings",
-        "children": []
-      },
-      {
-        "loaded": true,
-        "isPathHref": true,
-        "type": "link",
-        "title": "Store",
-        "path": "/settings/store",
-        "children": []
-      },
-      {
-        "loaded": true,
-        "isPathHref": true,
-        "type": "link",
-        "title": "Users",
-        "path": "/settings/users",
+        "type": "category",
+        "title": "Orders",
         "children": [
           {
             "loaded": true,
             "isPathHref": true,
             "type": "link",
-            "title": "Manage Invites",
-            "path": "/settings/users/invites",
+            "title": "Overview",
+            "path": "/orders",
+            "children": []
+          },
+          {
+            "loaded": true,
+            "isPathHref": true,
+            "type": "link",
+            "title": "Manage Details",
+            "path": "/orders/manage",
+            "children": []
+          },
+          {
+            "loaded": true,
+            "isPathHref": true,
+            "type": "link",
+            "title": "Manage Payments",
+            "path": "/orders/payments",
+            "children": []
+          },
+          {
+            "loaded": true,
+            "isPathHref": true,
+            "type": "link",
+            "title": "Manage Fulfillments",
+            "path": "/orders/fulfillments",
+            "children": []
+          },
+          {
+            "loaded": true,
+            "isPathHref": true,
+            "type": "link",
+            "title": "Edit Order Items",
+            "path": "/orders/edit",
+            "children": []
+          },
+          {
+            "loaded": true,
+            "isPathHref": true,
+            "type": "link",
+            "title": "Manage Returns",
+            "path": "/orders/returns",
+            "children": []
+          },
+          {
+            "loaded": true,
+            "isPathHref": true,
+            "type": "link",
+            "title": "Manage Exchanges",
+            "path": "/orders/exchanges",
+            "children": []
+          },
+          {
+            "loaded": true,
+            "isPathHref": true,
+            "type": "link",
+            "title": "Manage Claims",
+            "path": "/orders/claims",
             "children": []
           }
         ]
@@ -393,72 +133,88 @@ export const generatedSidebar = [
       {
         "loaded": true,
         "isPathHref": true,
-        "type": "link",
-        "title": "Regions",
-        "path": "/settings/regions",
-        "children": []
-      },
-      {
-        "loaded": true,
-        "isPathHref": true,
-        "type": "link",
-        "title": "Tax Regions",
-        "path": "/settings/tax-regions",
-        "children": []
-      },
-      {
-        "loaded": true,
-        "isPathHref": true,
-        "type": "link",
-        "title": "Return Reasons",
-        "path": "/settings/return-reasons",
-        "children": []
-      },
-      {
-        "loaded": true,
-        "isPathHref": true,
-        "type": "link",
-        "title": "Sales Channels",
-        "path": "/settings/sales-channels",
-        "children": []
-      },
-      {
-        "loaded": true,
-        "isPathHref": true,
-        "type": "link",
-        "title": "Product Types",
-        "path": "/settings/product-types",
-        "children": []
-      },
-      {
-        "loaded": true,
-        "isPathHref": true,
-        "type": "link",
-        "title": "Product Tags",
-        "path": "/settings/product-tags",
-        "children": []
-      },
-      {
-        "loaded": true,
-        "isPathHref": true,
-        "type": "link",
-        "title": "Location & Shipping",
-        "path": "/settings/locations-and-shipping",
+        "type": "category",
+        "title": "Products",
         "children": [
           {
             "loaded": true,
             "isPathHref": true,
             "type": "link",
-            "title": "Manage Locations",
-            "path": "/settings/locations-and-shipping/locations",
+            "title": "Overview",
+            "path": "/products",
             "children": []
           },
           {
             "loaded": true,
             "isPathHref": true,
             "type": "link",
-            "title": "Manage Shipping Profiles",
-            "path": "/settings/locations-and-shipping/shipping-profiles",
+            "title": "Create Product",
+            "path": "/products/create",
+            "children": [
+              {
+                "loaded": true,
+                "isPathHref": true,
+                "type": "link",
+                "title": "Multi-Part Product",
+                "path": "/products/create/multi-part",
+                "children": []
+              },
+              {
+                "loaded": true,
+                "isPathHref": true,
+                "type": "link",
+                "title": "Bundle Product",
+                "path": "/products/create/bundle",
+                "children": []
+              }
+            ]
+          },
+          {
+            "loaded": true,
+            "isPathHref": true,
+            "type": "link",
+            "title": "Edit Product",
+            "path": "/products/edit",
+            "children": []
+          },
+          {
+            "loaded": true,
+            "isPathHref": true,
+            "type": "link",
+            "title": "Manage Variants",
+            "path": "/products/variants",
+            "children": []
+          },
+          {
+            "loaded": true,
+            "isPathHref": true,
+            "type": "link",
+            "title": "Manage Collections",
+            "path": "/products/collections",
+            "children": []
+          },
+          {
+            "loaded": true,
+            "isPathHref": true,
+            "type": "link",
+            "title": "Manage Categories",
+            "path": "/products/categories",
+            "children": []
+          },
+          {
+            "loaded": true,
+            "isPathHref": true,
+            "type": "link",
+            "title": "Import Products",
+            "path": "/products/import",
+            "children": []
+          },
+          {
+            "loaded": true,
+            "isPathHref": true,
+            "type": "link",
+            "title": "Export Products",
+            "path": "/products/export",
             "children": []
           }
         ]
@@ -466,32 +222,31 @@ export const generatedSidebar = [
       {
         "loaded": true,
         "isPathHref": true,
-        "type": "link",
-        "title": "Developer Settings",
-        "path": "/settings/developer",
+        "type": "category",
+        "title": "Inventory",
         "children": [
           {
             "loaded": true,
             "isPathHref": true,
             "type": "link",
-            "title": "Publishable API Keys",
-            "path": "/settings/developer/publishable-api-keys",
+            "title": "Overview",
+            "path": "/inventory",
             "children": []
           },
           {
             "loaded": true,
             "isPathHref": true,
             "type": "link",
-            "title": "Secret API Keys",
-            "path": "/settings/developer/secret-api-keys",
+            "title": "Manage Inventory",
+            "path": "/inventory/inventory",
             "children": []
           },
           {
             "loaded": true,
             "isPathHref": true,
             "type": "link",
-            "title": "Workflows",
-            "path": "/settings/developer/workflows",
+            "title": "Manage Reservations",
+            "path": "/inventory/reservations",
             "children": []
           }
         ]
@@ -499,10 +254,261 @@ export const generatedSidebar = [
       {
         "loaded": true,
         "isPathHref": true,
-        "type": "link",
-        "title": "Profile",
-        "path": "/settings/profile",
-        "children": []
+        "type": "category",
+        "title": "Customers",
+        "children": [
+          {
+            "loaded": true,
+            "isPathHref": true,
+            "type": "link",
+            "title": "Overview",
+            "path": "/customers",
+            "children": []
+          },
+          {
+            "loaded": true,
+            "isPathHref": true,
+            "type": "link",
+            "title": "Manage Customers",
+            "path": "/customers/manage",
+            "children": []
+          },
+          {
+            "loaded": true,
+            "isPathHref": true,
+            "type": "link",
+            "title": "Manage Groups",
+            "path": "/customers/groups",
+            "children": []
+          }
+        ]
+      },
+      {
+        "loaded": true,
+        "isPathHref": true,
+        "type": "category",
+        "title": "Promotions",
+        "children": [
+          {
+            "loaded": true,
+            "isPathHref": true,
+            "type": "link",
+            "title": "Overview",
+            "path": "/promotions",
+            "children": []
+          },
+          {
+            "loaded": true,
+            "isPathHref": true,
+            "type": "link",
+            "title": "Create Promotion",
+            "path": "/promotions/create",
+            "children": []
+          },
+          {
+            "loaded": true,
+            "isPathHref": true,
+            "type": "link",
+            "title": "Manage Promotion",
+            "path": "/promotions/manage",
+            "children": []
+          },
+          {
+            "loaded": true,
+            "isPathHref": true,
+            "type": "link",
+            "title": "Manage Campaigns",
+            "path": "/promotions/campaigns",
+            "children": []
+          }
+        ]
+      },
+      {
+        "loaded": true,
+        "isPathHref": true,
+        "type": "category",
+        "title": "Price Lists",
+        "children": [
+          {
+            "loaded": true,
+            "isPathHref": true,
+            "type": "link",
+            "title": "Overview",
+            "path": "/price-lists",
+            "children": []
+          },
+          {
+            "loaded": true,
+            "isPathHref": true,
+            "type": "link",
+            "title": "Create Price List",
+            "path": "/price-lists/create",
+            "children": []
+          },
+          {
+            "loaded": true,
+            "isPathHref": true,
+            "type": "link",
+            "title": "Manage Price List",
+            "path": "/price-lists/manage",
+            "children": []
+          }
+        ]
+      },
+      {
+        "loaded": true,
+        "isPathHref": true,
+        "type": "category",
+        "title": "Settings",
+        "children": [
+          {
+            "loaded": true,
+            "isPathHref": true,
+            "type": "link",
+            "title": "Overview",
+            "path": "/settings",
+            "children": []
+          },
+          {
+            "loaded": true,
+            "isPathHref": true,
+            "type": "link",
+            "title": "Store",
+            "path": "/settings/store",
+            "children": []
+          },
+          {
+            "loaded": true,
+            "isPathHref": true,
+            "type": "link",
+            "title": "Users",
+            "path": "/settings/users",
+            "children": [
+              {
+                "loaded": true,
+                "isPathHref": true,
+                "type": "link",
+                "title": "Manage Invites",
+                "path": "/settings/users/invites",
+                "children": []
+              }
+            ]
+          },
+          {
+            "loaded": true,
+            "isPathHref": true,
+            "type": "link",
+            "title": "Regions",
+            "path": "/settings/regions",
+            "children": []
+          },
+          {
+            "loaded": true,
+            "isPathHref": true,
+            "type": "link",
+            "title": "Tax Regions",
+            "path": "/settings/tax-regions",
+            "children": []
+          },
+          {
+            "loaded": true,
+            "isPathHref": true,
+            "type": "link",
+            "title": "Return Reasons",
+            "path": "/settings/return-reasons",
+            "children": []
+          },
+          {
+            "loaded": true,
+            "isPathHref": true,
+            "type": "link",
+            "title": "Sales Channels",
+            "path": "/settings/sales-channels",
+            "children": []
+          },
+          {
+            "loaded": true,
+            "isPathHref": true,
+            "type": "link",
+            "title": "Product Types",
+            "path": "/settings/product-types",
+            "children": []
+          },
+          {
+            "loaded": true,
+            "isPathHref": true,
+            "type": "link",
+            "title": "Product Tags",
+            "path": "/settings/product-tags",
+            "children": []
+          },
+          {
+            "loaded": true,
+            "isPathHref": true,
+            "type": "link",
+            "title": "Location & Shipping",
+            "path": "/settings/locations-and-shipping",
+            "children": [
+              {
+                "loaded": true,
+                "isPathHref": true,
+                "type": "link",
+                "title": "Manage Locations",
+                "path": "/settings/locations-and-shipping/locations",
+                "children": []
+              },
+              {
+                "loaded": true,
+                "isPathHref": true,
+                "type": "link",
+                "title": "Manage Shipping Profiles",
+                "path": "/settings/locations-and-shipping/shipping-profiles",
+                "children": []
+              }
+            ]
+          },
+          {
+            "loaded": true,
+            "isPathHref": true,
+            "type": "link",
+            "title": "Developer Settings",
+            "path": "/settings/developer",
+            "children": [
+              {
+                "loaded": true,
+                "isPathHref": true,
+                "type": "link",
+                "title": "Publishable API Keys",
+                "path": "/settings/developer/publishable-api-keys",
+                "children": []
+              },
+              {
+                "loaded": true,
+                "isPathHref": true,
+                "type": "link",
+                "title": "Secret API Keys",
+                "path": "/settings/developer/secret-api-keys",
+                "children": []
+              },
+              {
+                "loaded": true,
+                "isPathHref": true,
+                "type": "link",
+                "title": "Workflows",
+                "path": "/settings/developer/workflows",
+                "children": []
+              }
+            ]
+          },
+          {
+            "loaded": true,
+            "isPathHref": true,
+            "type": "link",
+            "title": "Profile",
+            "path": "/settings/profile",
+            "children": []
+          }
+        ]
       }
     ]
   }

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,320 +1,322 @@
-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 = [
   {
-    type: "link",
-    path: "/",
-    title: "Introduction",
-  },
-  {
-    type: "link",
-    path: "/reset-password",
-    title: "Reset Password",
-  },
-  {
-    type: "separator",
-  },
-  {
-    type: "category",
-    title: "Tips",
-    autogenerate_path: "/tips",
-  },
-  {
-    type: "category",
-    title: "Orders",
-    children: [
+    sidebar_id: "user-guide",
+    title: "User Guide",
+    items: [
       {
         type: "link",
-        title: "Overview",
-        path: "/orders",
+        path: "/",
+        title: "Introduction",
       },
       {
         type: "link",
-        title: "Manage Details",
-        path: "/orders/manage",
+        path: "/reset-password",
+        title: "Reset Password",
       },
       {
-        type: "link",
-        title: "Manage Payments",
-        path: "/orders/payments",
+        type: "separator",
       },
       {
-        type: "link",
-        title: "Manage Fulfillments",
-        path: "/orders/fulfillments",
+        type: "category",
+        title: "Tips",
+        autogenerate_path: "/tips",
       },
       {
-        type: "link",
-        title: "Edit Order Items",
-        path: "/orders/edit",
-      },
-      {
-        type: "link",
-        title: "Manage Returns",
-        path: "/orders/returns",
-      },
-      {
-        type: "link",
-        title: "Manage Exchanges",
-        path: "/orders/exchanges",
-      },
-      {
-        type: "link",
-        title: "Manage Claims",
-        path: "/orders/claims",
-      },
-    ],
-  },
-  {
-    type: "category",
-    title: "Products",
-    children: [
-      {
-        type: "link",
-        title: "Overview",
-        path: "/products",
-      },
-      {
-        type: "link",
-        title: "Create Product",
-        path: "/products/create",
+        type: "category",
+        title: "Orders",
         children: [
           {
             type: "link",
-            title: "Multi-Part Product",
-            path: "/products/create/multi-part",
+            title: "Overview",
+            path: "/orders",
           },
           {
             type: "link",
-            title: "Bundle Product",
-            path: "/products/create/bundle",
+            title: "Manage Details",
+            path: "/orders/manage",
+          },
+          {
+            type: "link",
+            title: "Manage Payments",
+            path: "/orders/payments",
+          },
+          {
+            type: "link",
+            title: "Manage Fulfillments",
+            path: "/orders/fulfillments",
+          },
+          {
+            type: "link",
+            title: "Edit Order Items",
+            path: "/orders/edit",
+          },
+          {
+            type: "link",
+            title: "Manage Returns",
+            path: "/orders/returns",
+          },
+          {
+            type: "link",
+            title: "Manage Exchanges",
+            path: "/orders/exchanges",
+          },
+          {
+            type: "link",
+            title: "Manage Claims",
+            path: "/orders/claims",
           },
         ],
       },
       {
-        type: "link",
-        title: "Edit Product",
-        path: "/products/edit",
-      },
-      {
-        type: "link",
-        title: "Manage Variants",
-        path: "/products/variants",
-      },
-      {
-        type: "link",
-        title: "Manage Collections",
-        path: "/products/collections",
-      },
-      {
-        type: "link",
-        title: "Manage Categories",
-        path: "/products/categories",
-      },
-      {
-        type: "link",
-        title: "Import Products",
-        path: "/products/import",
-      },
-      {
-        type: "link",
-        title: "Export Products",
-        path: "/products/export",
-      },
-    ],
-  },
-  {
-    type: "category",
-    title: "Inventory",
-    children: [
-      {
-        type: "link",
-        title: "Overview",
-        path: "/inventory",
-      },
-      {
-        type: "link",
-        title: "Manage Inventory",
-        path: "/inventory/inventory",
-      },
-      {
-        type: "link",
-        title: "Manage Reservations",
-        path: "/inventory/reservations",
-      },
-    ],
-  },
-  {
-    type: "category",
-    title: "Customers",
-    children: [
-      {
-        type: "link",
-        title: "Overview",
-        path: "/customers",
-      },
-      {
-        type: "link",
-        title: "Manage Customers",
-        path: "/customers/manage",
-      },
-      {
-        type: "link",
-        title: "Manage Groups",
-        path: "/customers/groups",
-      },
-    ],
-  },
-  {
-    type: "category",
-    title: "Promotions",
-    children: [
-      {
-        type: "link",
-        title: "Overview",
-        path: "/promotions",
-      },
-      {
-        type: "link",
-        title: "Create Promotion",
-        path: "/promotions/create",
-      },
-      {
-        type: "link",
-        title: "Manage Promotion",
-        path: "/promotions/manage",
-      },
-      {
-        type: "link",
-        title: "Manage Campaigns",
-        path: "/promotions/campaigns",
-      },
-    ],
-  },
-  {
-    type: "category",
-    title: "Price Lists",
-    children: [
-      {
-        type: "link",
-        title: "Overview",
-        path: "/price-lists",
-      },
-      {
-        type: "link",
-        title: "Create Price List",
-        path: "/price-lists/create",
-      },
-      {
-        type: "link",
-        title: "Manage Price List",
-        path: "/price-lists/manage",
-      },
-    ],
-  },
-  {
-    type: "category",
-    title: "Settings",
-    children: [
-      {
-        type: "link",
-        title: "Overview",
-        path: "/settings",
-      },
-      {
-        type: "link",
-        title: "Store",
-        path: "/settings/store",
-      },
-      {
-        type: "link",
-        title: "Users",
-        path: "/settings/users",
+        type: "category",
+        title: "Products",
         children: [
           {
             type: "link",
-            title: "Manage Invites",
-            path: "/settings/users/invites",
+            title: "Overview",
+            path: "/products",
+          },
+          {
+            type: "link",
+            title: "Create Product",
+            path: "/products/create",
+            children: [
+              {
+                type: "link",
+                title: "Multi-Part Product",
+                path: "/products/create/multi-part",
+              },
+              {
+                type: "link",
+                title: "Bundle Product",
+                path: "/products/create/bundle",
+              },
+            ],
+          },
+          {
+            type: "link",
+            title: "Edit Product",
+            path: "/products/edit",
+          },
+          {
+            type: "link",
+            title: "Manage Variants",
+            path: "/products/variants",
+          },
+          {
+            type: "link",
+            title: "Manage Collections",
+            path: "/products/collections",
+          },
+          {
+            type: "link",
+            title: "Manage Categories",
+            path: "/products/categories",
+          },
+          {
+            type: "link",
+            title: "Import Products",
+            path: "/products/import",
+          },
+          {
+            type: "link",
+            title: "Export Products",
+            path: "/products/export",
           },
         ],
       },
       {
-        type: "link",
-        title: "Regions",
-        path: "/settings/regions",
-      },
-      {
-        type: "link",
-        title: "Tax Regions",
-        path: "/settings/tax-regions",
-      },
-      {
-        type: "link",
-        title: "Return Reasons",
-        path: "/settings/return-reasons",
-      },
-      {
-        type: "link",
-        title: "Sales Channels",
-        path: "/settings/sales-channels",
-      },
-      {
-        type: "link",
-        title: "Product Types",
-        path: "/settings/product-types",
-      },
-      {
-        type: "link",
-        title: "Product Tags",
-        path: "/settings/product-tags",
-      },
-      {
-        type: "link",
-        title: "Location & Shipping",
-        path: "/settings/locations-and-shipping",
+        type: "category",
+        title: "Inventory",
         children: [
           {
             type: "link",
-            title: "Manage Locations",
-            path: "/settings/locations-and-shipping/locations",
+            title: "Overview",
+            path: "/inventory",
           },
           {
             type: "link",
-            title: "Manage Shipping Profiles",
-            path: "/settings/locations-and-shipping/shipping-profiles",
+            title: "Manage Inventory",
+            path: "/inventory/inventory",
+          },
+          {
+            type: "link",
+            title: "Manage Reservations",
+            path: "/inventory/reservations",
           },
         ],
       },
       {
-        type: "link",
-        title: "Developer Settings",
-        path: "/settings/developer",
+        type: "category",
+        title: "Customers",
         children: [
           {
             type: "link",
-            title: "Publishable API Keys",
-            path: "/settings/developer/publishable-api-keys",
+            title: "Overview",
+            path: "/customers",
           },
           {
             type: "link",
-            title: "Secret API Keys",
-            path: "/settings/developer/secret-api-keys",
+            title: "Manage Customers",
+            path: "/customers/manage",
           },
           {
             type: "link",
-            title: "Workflows",
-            path: "/settings/developer/workflows",
+            title: "Manage Groups",
+            path: "/customers/groups",
           },
         ],
       },
       {
-        type: "link",
-        title: "Profile",
-        path: "/settings/profile",
+        type: "category",
+        title: "Promotions",
+        children: [
+          {
+            type: "link",
+            title: "Overview",
+            path: "/promotions",
+          },
+          {
+            type: "link",
+            title: "Create Promotion",
+            path: "/promotions/create",
+          },
+          {
+            type: "link",
+            title: "Manage Promotion",
+            path: "/promotions/manage",
+          },
+          {
+            type: "link",
+            title: "Manage Campaigns",
+            path: "/promotions/campaigns",
+          },
+        ],
+      },
+      {
+        type: "category",
+        title: "Price Lists",
+        children: [
+          {
+            type: "link",
+            title: "Overview",
+            path: "/price-lists",
+          },
+          {
+            type: "link",
+            title: "Create Price List",
+            path: "/price-lists/create",
+          },
+          {
+            type: "link",
+            title: "Manage Price List",
+            path: "/price-lists/manage",
+          },
+        ],
+      },
+      {
+        type: "category",
+        title: "Settings",
+        children: [
+          {
+            type: "link",
+            title: "Overview",
+            path: "/settings",
+          },
+          {
+            type: "link",
+            title: "Store",
+            path: "/settings/store",
+          },
+          {
+            type: "link",
+            title: "Users",
+            path: "/settings/users",
+            children: [
+              {
+                type: "link",
+                title: "Manage Invites",
+                path: "/settings/users/invites",
+              },
+            ],
+          },
+          {
+            type: "link",
+            title: "Regions",
+            path: "/settings/regions",
+          },
+          {
+            type: "link",
+            title: "Tax Regions",
+            path: "/settings/tax-regions",
+          },
+          {
+            type: "link",
+            title: "Return Reasons",
+            path: "/settings/return-reasons",
+          },
+          {
+            type: "link",
+            title: "Sales Channels",
+            path: "/settings/sales-channels",
+          },
+          {
+            type: "link",
+            title: "Product Types",
+            path: "/settings/product-types",
+          },
+          {
+            type: "link",
+            title: "Product Tags",
+            path: "/settings/product-tags",
+          },
+          {
+            type: "link",
+            title: "Location & Shipping",
+            path: "/settings/locations-and-shipping",
+            children: [
+              {
+                type: "link",
+                title: "Manage Locations",
+                path: "/settings/locations-and-shipping/locations",
+              },
+              {
+                type: "link",
+                title: "Manage Shipping Profiles",
+                path: "/settings/locations-and-shipping/shipping-profiles",
+              },
+            ],
+          },
+          {
+            type: "link",
+            title: "Developer Settings",
+            path: "/settings/developer",
+            children: [
+              {
+                type: "link",
+                title: "Publishable API Keys",
+                path: "/settings/developer/publishable-api-keys",
+              },
+              {
+                type: "link",
+                title: "Secret API Keys",
+                path: "/settings/developer/secret-api-keys",
+              },
+              {
+                type: "link",
+                title: "Workflows",
+                path: "/settings/developer/workflows",
+              },
+            ],
+          },
+          {
+            type: "link",
+            title: "Profile",
+            path: "/settings/profile",
+          },
+        ],
       },
     ],
   },
-])
+]

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) => {
-          if (existingItem.type !== "link" && existingItem.type !== "ref") {
-            return true
-          }
+        return existingChildren
+          ? existingChildren.every((existingItem) => {
+              if (existingItem.type !== "link" && existingItem.type !== "ref") {
+                return true
+              }
 
-          return existingItem.path !== tagItem.path
-        })
+              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) => {
-      delete child.sidebar_position
+    item.children = [
+      ...(item.children || []),
+      ...(await getAutogeneratedSidebarItems(item.autogenerate_path)).map(
+        (child) => {
+          delete child.sidebar_position
 
-      return child
-    })
+          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()
 
-export const SidebarChild = ({ item }: SidebarTitleProps) => {
-  const { goBack } = useSidebar()
+  const title = useMemo(() => {
+    if (!shownSidebar) {
+      return ""
+    }
+
+    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,33 +57,43 @@ 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) {
-      const isVisible = checkSidebarItemVisibility(
-        (ref.current.children.item(0) as HTMLElement) || ref.current,
-        !disableActiveTransition
-      )
-      if (isVisible) {
-        return
-      }
-      if (!disableActiveTransition) {
-        ref.current.scrollIntoView({
-          block: "center",
-        })
-      } else {
-        sidebarRef.current.scrollTo({
-          top: newTopCalculator,
-        })
-      }
+    if (
+      !active ||
+      !ref.current ||
+      !sidebarRef.current ||
+      isMobile ||
+      !isParentCategoryOpen
+    ) {
+      return
+    }
+
+    const isVisible = checkSidebarItemVisibility(
+      (ref.current.children.item(0) as HTMLElement) || ref.current,
+      !disableActiveTransition
+    )
+    if (isVisible) {
+      return
+    }
+    if (!disableActiveTransition) {
+      ref.current.scrollIntoView({
+        block: "center",
+      })
+    } else {
+      sidebarRef.current.scrollTo({
+        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",
-            ],
+            !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/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,12 +21,16 @@ export const getLocalSearch = <T extends BaseSearchRecord = BaseSearchRecord>({
   docs,
   searchableFields,
   options,
-}: GetLocalSearchInput<T>): LocalSearch<T> => {
-  const miniSearch = new MiniSearch({
-    fields: searchableFields,
-    ...options,
-  })
-  miniSearch.addAll(docs)
+}: GetLocalSearchInput<T>): LocalSearch<T> | undefined => {
+  try {
+    const miniSearch = new MiniSearch({
+      fields: searchableFields,
+      ...options,
+    })
+    miniSearch.addAll(docs)
 
-  return miniSearch as LocalSearch<T>
+    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"