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",
+          },
+        ],
       },
     ],
   },
-])
+]