docs: update docusaurus to v3 (#5625)

* update dependencies

* update onboarding mdx

* fixes for mdx issues

* fixes for mdx compatibility

* resolve mdx errors

* fixes in reference

* fix check errors

* revert change in vale action

* fix node version in action

* fix summary in markdown

www/apps/docs/src/theme/Admonition/Icon/Danger.tsx

@@ -0,0 +1,16 @@
+import React from "react"
+import type { IconProps } from "@medusajs/icons/dist/types"
+import { ExclamationCircleSolid } from "@medusajs/icons"
+import clsx from "clsx"
+
+export default function AdmonitionIconDanger({
+  className,
+  ...props
+}: IconProps): JSX.Element {
+  return (
+    <ExclamationCircleSolid
+      {...props}
+      className={clsx("inline-block mr-0.125 text-medusa-fg-error", className)}
+    />
+  )
+}

www/apps/docs/src/theme/Admonition/Icon/Info.tsx

@@ -0,0 +1,7 @@
+import React from "react"
+import AdmonitionIconNote from "./Note"
+import type { IconProps } from "@medusajs/icons/dist/types"
+
+export default function AdmonitionIconInfo(props: IconProps): JSX.Element {
+  return <AdmonitionIconNote {...props} />
+}

www/apps/docs/src/theme/Admonition/Icon/Note.tsx

@@ -0,0 +1,19 @@
+import React from "react"
+import { InformationCircleSolid } from "@medusajs/icons"
+import type { IconProps } from "@medusajs/icons/dist/types"
+import clsx from "clsx"
+
+export default function AdmonitionIconNote({
+  className,
+  ...props
+}: IconProps): JSX.Element {
+  return (
+    <InformationCircleSolid
+      {...props}
+      className={clsx(
+        "inline-block mr-0.125 text-medusa-tag-blue-icon",
+        className
+      )}
+    />
+  )
+}

www/apps/docs/src/theme/Admonition/Icon/Tip.tsx

@@ -0,0 +1,19 @@
+import { LightBulbSolid } from "@medusajs/icons"
+import type { IconProps } from "@medusajs/icons/dist/types"
+import clsx from "clsx"
+import React from "react"
+
+export default function AdmonitionIconTip({
+  className,
+  ...props
+}: IconProps): JSX.Element {
+  return (
+    <LightBulbSolid
+      {...props}
+      className={clsx(
+        "inline-block mr-0.125 text-medusa-tag-orange-icon",
+        className
+      )}
+    />
+  )
+}

www/apps/docs/src/theme/Admonition/Icon/Warning.tsx

@@ -0,0 +1,7 @@
+import React from "react"
+import AdmonitionIconDanger from "./Danger"
+import type { IconProps } from "@medusajs/icons/dist/types"
+
+export default function AdmonitionIconCaution(props: IconProps): JSX.Element {
+  return <AdmonitionIconDanger {...props} />
+}

www/apps/docs/src/theme/Admonition/Layout/index.tsx

@@ -0,0 +1,51 @@
+import React, { type ReactNode } from "react"
+import clsx from "clsx"
+
+import type { Props } from "@theme/Admonition/Layout"
+
+function AdmonitionContainer({
+  className,
+  children,
+}: Pick<Props, "type" | "className"> & { children: ReactNode }) {
+  return (
+    <div
+      className={clsx(
+        "p-1 border border-solid border-medusa-border-base rounded",
+        "bg-medusa-bg-subtle dark:bg-medusa-bg-base shadow-none",
+        "[&_a]:no-underline [&_a]:text-medusa-fg-interactive hover:[&_a]:text-medusa-fg-interactive-hover ",
+        "mb-2 alert",
+        className
+      )}
+    >
+      <div className={clsx("flex")}>{children}</div>
+    </div>
+  )
+}
+
+function AdmonitionHeading({ icon }: Pick<Props, "icon">) {
+  return <span className={clsx("inline-block h-1.5 w-1.5 mr-1")}>{icon}</span>
+}
+
+function AdmonitionContent({ children }: Pick<Props, "children">) {
+  return children ? (
+    <div
+      className={clsx(
+        "text-medusa-fg-subtle",
+        "text-medium flex-1 [&>*:last-child]:mb-0",
+        "[&>p>code]:px-0.5 [&>p>code]:text-code-label"
+      )}
+    >
+      {children}
+    </div>
+  ) : null
+}
+
+export default function AdmonitionLayout(props: Props): JSX.Element {
+  const { type, icon, children, className } = props
+  return (
+    <AdmonitionContainer type={type} className={className}>
+      <AdmonitionHeading icon={icon} />
+      <AdmonitionContent>{children}</AdmonitionContent>
+    </AdmonitionContainer>
+  )
+}

www/apps/docs/src/theme/Admonition/index.tsx

@@ -1,188 +0,0 @@
-import React, { type ReactNode } from "react"
-import clsx from "clsx"
-import Translate from "@docusaurus/Translate"
-import type { Props } from "@theme/Admonition"
-import {
-  ExclamationCircleSolid,
-  InformationCircleSolid,
-  LightBulbSolid,
-} from "@medusajs/icons"
-
-function NoteIcon() {
-  return (
-    <InformationCircleSolid className="inline-block mr-0.125 text-medusa-tag-blue-icon" />
-  )
-}
-
-function TipIcon() {
-  return (
-    <LightBulbSolid className="inline-block mr-0.125 text-medusa-tag-orange-icon" />
-  )
-}
-
-function DangerIcon() {
-  return (
-    <ExclamationCircleSolid className="inline-block mr-0.125 text-medusa-fg-error" />
-  )
-}
-
-function InfoIcon() {
-  return NoteIcon()
-}
-
-function CautionIcon() {
-  return DangerIcon()
-}
-
-type AdmonitionConfig = {
-  iconComponent: React.ComponentType
-  infimaClassName: string
-  label: ReactNode
-}
-
-// eslint-disable-next-line @typescript-eslint/consistent-indexed-object-style
-const AdmonitionConfigs: Record<Props["type"], AdmonitionConfig> = {
-  note: {
-    infimaClassName: "secondary",
-    iconComponent: NoteIcon,
-    label: (
-      <Translate
-        id="theme.admonition.note"
-        description="The default label used for the Note admonition (:::note)"
-      >
-        note
-      </Translate>
-    ),
-  },
-  tip: {
-    infimaClassName: "success",
-    iconComponent: TipIcon,
-    label: (
-      <Translate
-        id="theme.admonition.tip"
-        description="The default label used for the Tip admonition (:::tip)"
-      >
-        tip
-      </Translate>
-    ),
-  },
-  danger: {
-    infimaClassName: "danger",
-    iconComponent: DangerIcon,
-    label: (
-      <Translate
-        id="theme.admonition.danger"
-        description="The default label used for the Danger admonition (:::danger)"
-      >
-        danger
-      </Translate>
-    ),
-  },
-  info: {
-    infimaClassName: "info",
-    iconComponent: InfoIcon,
-    label: (
-      <Translate
-        id="theme.admonition.info"
-        description="The default label used for the Info admonition (:::info)"
-      >
-        info
-      </Translate>
-    ),
-  },
-  caution: {
-    infimaClassName: "warning",
-    iconComponent: CautionIcon,
-    label: (
-      <Translate
-        id="theme.admonition.caution"
-        description="The default label used for the Caution admonition (:::caution)"
-      >
-        caution
-      </Translate>
-    ),
-  },
-}
-
-// Legacy aliases, undocumented but kept for retro-compatibility
-const aliases = {
-  secondary: "note",
-  important: "info",
-  success: "tip",
-  warning: "danger",
-} as const
-
-function getAdmonitionConfig(unsafeType: string): AdmonitionConfig {
-  const type =
-    (aliases as { [key: string]: Props["type"] })[unsafeType] ?? unsafeType
-  const config = (AdmonitionConfigs as { [key: string]: AdmonitionConfig })[
-    type
-  ]
-  if (config) {
-    return config
-  }
-  console.warn(
-    `No admonition config found for admonition type "${type}". Using Info as fallback.`
-  )
-  return AdmonitionConfigs.info
-}
-
-// Workaround because it's difficult in MDX v1 to provide a MDX title as props
-// See https://github.com/facebook/docusaurus/pull/7152#issuecomment-1145779682
-function extractMDXAdmonitionTitle(children: ReactNode): {
-  mdxAdmonitionTitle: ReactNode | undefined
-  rest: ReactNode
-} {
-  const items = React.Children.toArray(children)
-  const mdxAdmonitionTitle = items.find(
-    (item) =>
-      React.isValidElement(item) &&
-      (item.props as { mdxType: string } | null)?.mdxType ===
-        "mdxAdmonitionTitle"
-  )
-  const rest = <>{items.filter((item) => item !== mdxAdmonitionTitle)}</>
-  return {
-    mdxAdmonitionTitle,
-    rest,
-  }
-}
-
-function processAdmonitionProps(props: Props): Props {
-  const { mdxAdmonitionTitle, rest } = extractMDXAdmonitionTitle(props.children)
-  return {
-    ...props,
-    title: props.title ?? mdxAdmonitionTitle,
-    children: rest,
-  }
-}
-
-export default function Admonition(props: Props): JSX.Element {
-  const { children, type, icon: iconProp } = processAdmonitionProps(props)
-
-  const typeConfig = getAdmonitionConfig(type)
-  const { iconComponent: IconComponent } = typeConfig
-  const icon = iconProp ?? <IconComponent />
-  return (
-    <div
-      className={clsx(
-        "p-1 border border-solid border-medusa-border-base rounded",
-        "bg-medusa-bg-subtle dark:bg-medusa-bg-base shadow-none",
-        "[&_a]:no-underline [&_a]:text-medusa-fg-interactive hover:[&_a]:text-medusa-fg-interactive-hover ",
-        "mb-2 alert"
-      )}
-    >
-      <div className={clsx("flex")}>
-        <span className={clsx("inline-block h-1.5 w-1.5 mr-1")}>{icon}</span>
-        <div
-          className={clsx(
-            "text-medusa-fg-subtle",
-            "text-medium flex-1 [&>*:last-child]:mb-0",
-            "[&>p>code]:px-0.5 [&>p>code]:text-code-label"
-          )}
-        >
-          {children}
-        </div>
-      </div>
-    </div>
-  )
-}

www/apps/docs/src/theme/AnnouncementBar/CloseButton/index.tsx

@@ -1,7 +1,7 @@
 import React from "react"
 import clsx from "clsx"
 import { translate } from "@docusaurus/Translate"
-import IconClose from "../../Icon/Close"
+import IconClose from "@theme/Icon/Close"
 import type { Props } from "@theme/AnnouncementBar/CloseButton"
 
 export default function AnnouncementBarCloseButton(

www/apps/docs/src/theme/AnnouncementBar/index.tsx

@@ -3,6 +3,7 @@ import { useThemeConfig } from "@docusaurus/theme-common"
 import { useAnnouncementBar } from "@docusaurus/theme-common/internal"
 import AnnouncementBarCloseButton from "@theme/AnnouncementBar/CloseButton"
 import AnnouncementBarContent from "@theme/AnnouncementBar/Content"
+
 import clsx from "clsx"
 import { Bordered } from "docs-ui"
 import { BellAlertSolid } from "@medusajs/icons"

www/apps/docs/src/theme/CodeBlock/Content/String.tsx

@@ -8,15 +8,22 @@ import {
   containsLineNumbers,
   useCodeWordWrap,
 } from "@docusaurus/theme-common/internal"
-import Highlight, { defaultProps, type Language } from "prism-react-renderer"
+import { Highlight, type Language } from "prism-react-renderer"
 import Line from "@theme/CodeBlock/Line"
 import Container from "@theme/CodeBlock/Container"
 import type { Props } from "@theme/CodeBlock/Content/String"
+import { Tooltip, CopyButton } from "docs-ui"
 import useIsBrowser from "@docusaurus/useIsBrowser"
 import { ThemeConfig } from "@medusajs/docs"
-import { CopyButton, Tooltip } from "docs-ui"
 import { ExclamationCircleSolid, SquareTwoStackSolid } from "@medusajs/icons"
 
+// Prism languages are always lowercase
+// We want to fail-safe and allow both "php" and "PHP"
+// See https://github.com/facebook/docusaurus/issues/9012
+function normalizeLanguage(language: string | undefined): string | undefined {
+  return language?.toLowerCase()
+}
+
 export default function CodeBlockString({
   children,
   className: blockClassName = "",
@@ -31,8 +38,10 @@ export default function CodeBlockString({
     prism: { defaultLanguage, magicComments },
     reportCodeLinkPrefix = "",
   } = useThemeConfig() as ThemeConfig
-  const language =
+  const language = normalizeLanguage(
     languageProp ?? parseLanguage(blockClassName) ?? defaultLanguage
+  )
+
   const prismTheme = usePrismTheme()
   const wordWrap = useCodeWordWrap()
   const isBrowser = useIsBrowser()
@@ -62,7 +71,6 @@ export default function CodeBlockString({
       {title && <div>{title}</div>}
       <div className={clsx("relative rounded-[inherit]")}>
         <Highlight
-          {...defaultProps}
           theme={prismTheme}
           code={code}
           language={(language ?? "text") as Language}

www/apps/docs/src/theme/CodeBlock/index.tsx

@@ -36,7 +36,6 @@ export default function CodeBlock({
 
   const title = props.title
   delete props.title
-
   return (
     <div className="code-wrapper">
       {title && <div className="code-header">{title}</div>}

www/apps/docs/src/theme/DocCard/index.tsx

@@ -2,7 +2,7 @@ import React, { type ReactNode } from "react"
 import clsx from "clsx"
 import Link from "@docusaurus/Link"
 import {
-  findFirstCategoryLink,
+  findFirstSidebarItemLink,
   useDocById,
 } from "@docusaurus/theme-common/internal"
 import isInternalUrl from "@docusaurus/isInternalUrl"
@@ -14,8 +14,8 @@ import {
   ModifiedSidebarItem,
 } from "@medusajs/docs"
 import { Badge } from "docs-ui"
-import BorderedIcon from "../../components/BorderedIcon"
 import Icons from "../Icon"
+import BorderedIcon from "../../components/BorderedIcon"
 
 type ModifiedProps = {
   item: ModifiedDocCard
@@ -185,12 +185,14 @@ function CardCategory({
 }: {
   item: ModifiedDocCardItemCategory
 }): JSX.Element | null {
-  const href = findFirstCategoryLink(item)
+  const href = findFirstSidebarItemLink(item)
   const icon = getCardIcon(item)
+
   // Unexpected: categories that don't have a link have been filtered upfront
   if (!href) {
     return null
   }
+
   return (
     <CardLayout
       {...item}
@@ -217,7 +219,6 @@ function CardCategory({
 function CardLink({ item }: { item: ModifiedDocCardItemLink }): JSX.Element {
   const icon = getCardIcon(item)
   const doc = useDocById(item.docId ?? undefined)
-
   return (
     <CardLayout
       {...item}

www/apps/docs/src/theme/DocCardList/index.tsx

@@ -7,6 +7,10 @@ import {
 import DocCard from "@theme/DocCard"
 import type { Props } from "@theme/DocCardList"
 
+type ModifiedProps = {
+  colSize?: string
+} & Props
+
 function DocCardListForCurrentSidebarCategory({
   className,
   ...rest
@@ -15,10 +19,6 @@ function DocCardListForCurrentSidebarCategory({
   return <DocCardList className={className} {...rest} items={category.items} />
 }
 
-type ModifiedProps = {
-  colSize?: string
-} & Props
-
 export default function DocCardList(props: ModifiedProps): JSX.Element {
   const { items, className } = props
   if (!items) {
@@ -27,7 +27,6 @@ export default function DocCardList(props: ModifiedProps): JSX.Element {
   const filteredItems = filterDocCardListItems(items).filter(
     (item) => !item.customProps?.exclude_from_doclist
   )
-
   return (
     <section
       className={clsx("cards-grid", `grid-${props.colSize || "4"}`, className)}

www/apps/docs/src/theme/DocItem/Content/index.tsx

@@ -6,7 +6,7 @@ import Heading from "@theme/Heading"
 import MDXContent from "@theme/MDXContent"
 import type { Props } from "@theme/DocItem/Content"
 import { DocContextValue } from "@medusajs/docs"
-import { Badge, type BadgeVariant } from "docs-ui"
+import { Badge, BadgeVariant } from "docs-ui"
 
 /**
  Title can be declared inside md content or declared through
@@ -33,7 +33,6 @@ export default function DocItemContent({ children }: Props): JSX.Element {
     frontMatter: { badge },
   } = useDoc() as DocContextValue
   const syntheticTitle = useSyntheticTitle()
-
   return (
     <div className={clsx(ThemeClassNames.docs.docMarkdown, "markdown")}>
       {syntheticTitle && (

www/apps/docs/src/theme/DocItem/Footer/index.tsx

@@ -4,15 +4,14 @@ import type FooterType from "@theme/DocItem/Footer"
 import type { WrapperProps } from "@docusaurus/types"
 import { useDoc } from "@docusaurus/theme-common/internal"
 import { useThemeConfig } from "@docusaurus/theme-common"
-import { ThemeConfig } from "@medusajs/docs"
-import Feedback from "@site/src/components/Feedback"
+import type { ThemeConfig } from "@medusajs/docs"
+import Feedback from "../../../components/Feedback"
 
 type Props = WrapperProps<typeof FooterType>
 
 export default function FooterWrapper(props: Props): JSX.Element {
   const { metadata } = useDoc()
   const { footerFeedback = { event: "" } } = useThemeConfig() as ThemeConfig
-
   return (
     <>
       {!metadata.frontMatter?.hide_footer && (

www/apps/docs/src/theme/DocItem/Layout/index.tsx

@@ -10,9 +10,10 @@ import DocItemTOCMobile from "@theme/DocItem/TOC/Mobile"
 import DocItemTOCDesktop from "@theme/DocItem/TOC/Desktop"
 import DocItemContent from "@theme/DocItem/Content"
 import DocBreadcrumbs from "@theme/DocBreadcrumbs"
+import Unlisted from "@theme/Unlisted"
 import type { Props } from "@theme/DocItem/Layout"
-import Footer from "@theme/Footer"
 import { useSidebar } from "../../../providers/Sidebar"
+import Footer from "@theme/Footer"
 
 /**
  * Decide if the toc should be rendered, on mobile or desktop viewports
@@ -40,6 +41,9 @@ function useDocTOC() {
 
 export default function DocItemLayout({ children }: Props): JSX.Element {
   const docTOC = useDocTOC()
+  const {
+    metadata: { unlisted },
+  } = useDoc()
   const sidebarContext = useSidebar()
   return (
     <div className="row m-0">
@@ -51,6 +55,7 @@ export default function DocItemLayout({ children }: Props): JSX.Element {
           !sidebarContext?.hiddenSidebarContainer && "!max-w-[720px]"
         )}
       >
+        {unlisted && <Unlisted />}
         <DocVersionBanner />
         <div>
           <article className={clsx("[&>*:first-child]:mt-0")}>

www/apps/docs/src/theme/DocPage/index.tsx

@@ -1,73 +0,0 @@
-import React from "react"
-import clsx from "clsx"
-import {
-  HtmlClassNameProvider,
-  ThemeClassNames,
-  PageMetadata,
-} from "@docusaurus/theme-common"
-import {
-  docVersionSearchTag,
-  DocsSidebarProvider,
-  DocsVersionProvider,
-  useDocRouteMetadata,
-} from "@docusaurus/theme-common/internal"
-import DocPageLayout from "@theme/DocPage/Layout"
-import NotFound from "@theme/NotFound"
-import SearchMetadata from "@theme/SearchMetadata"
-import type { Props } from "@theme/DocPage"
-import SidebarProvider from "@site/src/providers/Sidebar"
-import DocsProviders from "../../providers/DocsProviders"
-
-function DocPageMetadata(props: Props): JSX.Element {
-  const { versionMetadata } = props
-  return (
-    <>
-      <SearchMetadata
-        version={versionMetadata.version}
-        tag={docVersionSearchTag(
-          versionMetadata.pluginId,
-          versionMetadata.version
-        )}
-      />
-      <PageMetadata>
-        {versionMetadata.noIndex && (
-          <meta name="robots" content="noindex, nofollow" />
-        )}
-      </PageMetadata>
-    </>
-  )
-}
-
-export default function DocPage(props: Props): JSX.Element {
-  const { versionMetadata } = props
-  const currentDocRouteMetadata = useDocRouteMetadata(props)
-  if (!currentDocRouteMetadata) {
-    return <NotFound />
-  }
-  const { docElement, sidebarName, sidebarItems } = currentDocRouteMetadata
-
-  return (
-    <>
-      <DocPageMetadata {...props} />
-      <HtmlClassNameProvider
-        className={clsx(
-          // TODO: it should be removed from here
-          ThemeClassNames.wrapper.docsPages,
-          ThemeClassNames.page.docsDocPage,
-          props.versionMetadata.className
-          // sidebarName && "doc-has-sidebar"
-        )}
-      >
-        <DocsVersionProvider version={versionMetadata}>
-          <DocsProviders>
-            <DocsSidebarProvider name={sidebarName} items={sidebarItems}>
-              <SidebarProvider sidebarName={sidebarName}>
-                <DocPageLayout>{docElement}</DocPageLayout>
-              </SidebarProvider>
-            </DocsSidebarProvider>
-          </DocsProviders>
-        </DocsVersionProvider>
-      </HtmlClassNameProvider>
-    </>
-  )
-}

www/apps/docs/src/theme/DocRoot/Layout/Main/index.tsx

@@ -1,10 +1,11 @@
 import React from "react"
 import clsx from "clsx"
 import { useDocsSidebar } from "@docusaurus/theme-common/internal"
-import type { Props } from "@theme/DocPage/Layout/Main"
-import { useSidebar } from "@site/src/providers/Sidebar"
+import type { Props } from "@theme/DocRoot/Layout/Main"
 
-export default function DocPageLayoutMain({ children }: Props): JSX.Element {
+import { useSidebar } from "../../../../providers/Sidebar"
+
+export default function DocRootLayoutMain({ children }: Props): JSX.Element {
   const sidebar = useDocsSidebar()
   const sidebarContext = useSidebar()
   return (

www/apps/docs/src/theme/DocRoot/Layout/Sidebar/index.tsx

@@ -4,9 +4,9 @@ import { ThemeClassNames } from "@docusaurus/theme-common"
 import { useDocsSidebar } from "@docusaurus/theme-common/internal"
 import { useLocation } from "@docusaurus/router"
 import DocSidebar from "@theme/DocSidebar"
-import type { Props } from "@theme/DocPage/Layout/Sidebar"
-import { SwitchTransition, CSSTransition } from "react-transition-group"
-import { useSidebar } from "@site/src/providers/Sidebar"
+import type { Props } from "@theme/DocRoot/Layout/Sidebar"
+import { useSidebar } from "../../../../providers/Sidebar"
+import { CSSTransition, SwitchTransition } from "react-transition-group"
 
 // Reset sidebar state when sidebar changes
 // Use React key to unmount/remount the children
@@ -20,7 +20,7 @@ function ResetOnSidebarChange({ children }: { children: ReactNode }) {
   )
 }
 
-export default function DocPageLayoutSidebar({
+export default function DocRootLayoutSidebar({
   sidebar,
   hiddenSidebarContainer,
 }: Props): JSX.Element {

www/apps/docs/src/theme/DocRoot/Layout/index.tsx

@@ -1,27 +1,26 @@
 import React from "react"
 import { useDocsSidebar } from "@docusaurus/theme-common/internal"
-import Layout from "@theme/Layout"
 import BackToTopButton from "@theme/BackToTopButton"
-import DocPageLayoutSidebar from "@theme/DocPage/Layout/Sidebar"
-import DocPageLayoutMain from "@theme/DocPage/Layout/Main"
-import type { Props } from "@theme/DocPage/Layout"
-import clsx from "clsx"
-import { useSidebar } from "../../../providers/Sidebar"
+import DocRootLayoutSidebar from "@theme/DocRoot/Layout/Sidebar"
+import DocRootLayoutMain from "@theme/DocRoot/Layout/Main"
+import type { Props } from "@theme/DocRoot/Layout"
+
 import useOnboarding from "../../../hooks/use-onboarding"
 import useCurrentLearningPath from "../../../hooks/use-current-learning-path"
+import { useSidebar } from "../../../providers/Sidebar"
+import clsx from "clsx"
 
-export default function DocPageLayout({ children }: Props): JSX.Element {
+export default function DocRootLayout({ children }: Props): JSX.Element {
   const sidebar = useDocsSidebar()
   const sidebarContext = useSidebar()
   useOnboarding()
   useCurrentLearningPath()
-
   return (
-    <Layout wrapperClassName={clsx("flex flex-[1_0_auto]")}>
+    <div className={clsx("flex flex-[1_0_auto]")}>
       <BackToTopButton />
       <div className={clsx("flex w-full flex-[1_0]")}>
         {sidebar && (
-          <DocPageLayoutSidebar
+          <DocRootLayoutSidebar
             sidebar={sidebar.items}
             hiddenSidebarContainer={sidebarContext?.hiddenSidebarContainer}
             setHiddenSidebarContainer={
@@ -29,12 +28,12 @@ export default function DocPageLayout({ children }: Props): JSX.Element {
             }
           />
         )}
-        <DocPageLayoutMain
+        <DocRootLayoutMain
           hiddenSidebarContainer={sidebarContext?.hiddenSidebarContainer}
         >
           {children}
-        </DocPageLayoutMain>
+        </DocRootLayoutMain>
       </div>
-    </Layout>
+    </div>
   )
 }

www/apps/docs/src/theme/DocRoot/index.tsx

@@ -0,0 +1,33 @@
+import React from "react"
+import clsx from "clsx"
+import {
+  HtmlClassNameProvider,
+  ThemeClassNames,
+} from "@docusaurus/theme-common"
+import {
+  DocsSidebarProvider,
+  useDocRootMetadata,
+} from "@docusaurus/theme-common/internal"
+import DocRootLayout from "@theme/DocRoot/Layout"
+import NotFoundContent from "@theme/NotFound/Content"
+import type { Props } from "@theme/DocRoot"
+import SidebarProvider from "../../providers/Sidebar"
+
+export default function DocRoot(props: Props): JSX.Element {
+  const currentDocRouteMetadata = useDocRootMetadata(props)
+  if (!currentDocRouteMetadata) {
+    // We only render the not found content to avoid a double layout
+    // see https://github.com/facebook/docusaurus/pull/7966#pullrequestreview-1077276692
+    return <NotFoundContent />
+  }
+  const { docElement, sidebarName, sidebarItems } = currentDocRouteMetadata
+  return (
+    <HtmlClassNameProvider className={clsx(ThemeClassNames.page.docsDocPage)}>
+      <DocsSidebarProvider name={sidebarName} items={sidebarItems}>
+        <SidebarProvider sidebarName={sidebarName}>
+          <DocRootLayout>{docElement}</DocRootLayout>
+        </SidebarProvider>
+      </DocsSidebarProvider>
+    </HtmlClassNameProvider>
+  )
+}

www/apps/docs/src/theme/DocSidebar/Desktop/index.tsx

@@ -1,11 +1,11 @@
 import React, { useEffect, useRef } from "react"
 import clsx from "clsx"
 import { useThemeConfig } from "@docusaurus/theme-common"
+import AnnouncementBar from "@theme/AnnouncementBar"
 import Content from "@theme/DocSidebar/Desktop/Content"
 import type { Props } from "@theme/DocSidebar/Desktop"
 import useIsBrowser from "@docusaurus/useIsBrowser"
 import { useLocation } from "@docusaurus/router"
-import AnnouncementBar from "../../AnnouncementBar/index"
 
 function DocSidebarDesktop({ path, sidebar }: Props) {
   const {

www/apps/docs/src/theme/DocSidebarItem/Category/index.tsx

@@ -9,7 +9,7 @@ import {
 } from "@docusaurus/theme-common"
 import {
   isActiveSidebarItem,
-  findFirstCategoryLink,
+  findFirstSidebarItemLink,
   useDocSidebarItemsExpandedState,
   isSamePath,
 } from "@docusaurus/theme-common/internal"
@@ -59,7 +59,7 @@ function useCategoryHrefWithSSRFallback(
 ): string | undefined {
   const isBrowser = useIsBrowser()
   return useMemo(() => {
-    if (item.href) {
+    if (item.href && !item.linkUnlisted) {
       return item.href
     }
     // In these cases, it's not necessary to render a fallback
@@ -67,7 +67,7 @@ function useCategoryHrefWithSSRFallback(
     if (isBrowser || !item.collapsible) {
       return undefined
     }
-    return findFirstCategoryLink(item)
+    return findFirstSidebarItemLink(item)
   }, [item, isBrowser])
 }
 
@@ -75,6 +75,7 @@ function CollapseButton({
   categoryLabel,
   onClick,
 }: {
+  collapsed: boolean
   categoryLabel: string
   onClick: ComponentProps<"button">["onClick"]
 }) {
@@ -150,9 +151,6 @@ export default function DocSidebarItemCategory({
         ThemeClassNames.docs.docSidebarItemCategory,
         ThemeClassNames.docs.docSidebarItemCategoryLevel(level),
         "menu__list-item",
-        // {
-        //   "menu__list-item--collapsed": collapsed,
-        // },
         className,
         customProps?.sidebar_is_title && "sidebar-title",
         customProps?.sidebar_is_group_headline && "sidebar-group-headline",
@@ -210,6 +208,7 @@ export default function DocSidebarItemCategory({
         </Link>
         {href && collapsible && (
           <CollapseButton
+            collapsed={collapsed}
             categoryLabel={label}
             onClick={(e) => {
               e.preventDefault()

www/apps/docs/src/theme/DocSidebarItem/Link/index.tsx

@@ -7,8 +7,8 @@ import isInternalUrl from "@docusaurus/isInternalUrl"
 import IconExternalLink from "@theme/Icon/ExternalLink"
 import type { Props } from "@theme/DocSidebarItem/Link"
 import { ModifiedPropSidebarItemLink } from "@medusajs/docs"
-import DocSidebarItemIcon from "../../../components/DocSidebarItemIcon"
 import { Badge } from "docs-ui"
+import DocSidebarItemIcon from "../../../components/DocSidebarItemIcon"
 
 type ModifiedProps = Props & {
   item: ModifiedPropSidebarItemLink

www/apps/docs/src/theme/DocSidebarItems/index.tsx

@@ -0,0 +1,54 @@
+import React, { memo, useMemo } from "react"
+import {
+  DocSidebarItemsExpandedStateProvider,
+  isActiveSidebarItem,
+} from "@docusaurus/theme-common/internal"
+import DocSidebarItem from "@theme/DocSidebarItem"
+import type { PropSidebarItem } from "@docusaurus/plugin-content-docs"
+
+import type { Props } from "@theme/DocSidebarItems"
+
+function DocSidebarItems({ items, ...props }: Props): JSX.Element {
+  // This acts as a fix to a bug in docusaurus which should be part
+  // of an upcoming release.
+  function isVisibleSidebarItem(
+    item: PropSidebarItem,
+    activePath: string
+  ): boolean {
+    switch (item.type) {
+      case "category":
+        return (
+          isActiveSidebarItem(item, activePath) ||
+          item.items.some((subItem) =>
+            isVisibleSidebarItem(subItem, activePath)
+          )
+        )
+      case "link":
+        // An unlisted item remains visible if it is active
+        return !item.unlisted || isActiveSidebarItem(item, activePath)
+      default:
+        return true
+    }
+  }
+  function useVisibleSidebarItems(
+    items: readonly PropSidebarItem[],
+    activePath: string
+  ): PropSidebarItem[] {
+    return useMemo(
+      () => items.filter((item) => isVisibleSidebarItem(item, activePath)),
+      [items, activePath]
+    )
+  }
+
+  const visibleItems = useVisibleSidebarItems(items, props.activePath)
+  return (
+    <DocSidebarItemsExpandedStateProvider>
+      {visibleItems.map((item, index) => (
+        <DocSidebarItem key={index} item={item} index={index} {...props} />
+      ))}
+    </DocSidebarItemsExpandedStateProvider>
+  )
+}
+
+// Optimize sidebar at each "level"
+export default memo(DocSidebarItems)

www/apps/docs/src/theme/DocsRoot/index.tsx

@@ -0,0 +1,21 @@
+import React from "react"
+import clsx from "clsx"
+import {
+  ThemeClassNames,
+  HtmlClassNameProvider,
+} from "@docusaurus/theme-common"
+import renderRoutes from "@docusaurus/renderRoutes"
+import Layout from "@theme/Layout"
+
+import type { Props } from "@theme/DocVersionRoot"
+import DocsProviders from "../../providers/DocsProviders"
+
+export default function DocsRoot(props: Props): JSX.Element {
+  return (
+    <HtmlClassNameProvider className={clsx(ThemeClassNames.wrapper.docsPages)}>
+      <DocsProviders>
+        <Layout>{renderRoutes(props.route.routes!)}</Layout>
+      </DocsProviders>
+    </HtmlClassNameProvider>
+  )
+}

www/apps/docs/src/theme/EditThisPage/index.tsx

@@ -2,8 +2,8 @@ import React from "react"
 import Translate from "@docusaurus/Translate"
 import { ThemeClassNames } from "@docusaurus/theme-common"
 import type { Props } from "@theme/EditThisPage"
-import clsx from "clsx"
 import { Button } from "docs-ui"
+import clsx from "clsx"
 
 export default function EditThisPage({ editUrl }: Props): JSX.Element {
   return (

www/apps/docs/src/theme/Footer/Layout/index.tsx

@@ -1,8 +1,8 @@
 import React from "react"
 import clsx from "clsx"
 import type { Props } from "@theme/Footer/Layout"
-import { useThemeConfig } from "@docusaurus/theme-common"
 import { ThemeConfig } from "@medusajs/docs"
+import { useThemeConfig } from "@docusaurus/theme-common"
 import SocialLinks from "@site/src/components/Footer/SocialLinks"
 
 export default function FooterLayout({

www/apps/docs/src/theme/Footer/index.tsx

@@ -1,26 +0,0 @@
-import React from "react"
-
-import { useThemeConfig } from "@docusaurus/theme-common"
-import FooterLinks from "@theme/Footer/Links"
-import FooterLogo from "@theme/Footer/Logo"
-import FooterCopyright from "@theme/Footer/Copyright"
-import FooterLayout from "@theme/Footer/Layout"
-
-function Footer(): JSX.Element | null {
-  const { footer } = useThemeConfig()
-  if (!footer) {
-    return null
-  }
-  const { copyright, links, logo, style } = footer
-
-  return (
-    <FooterLayout
-      style={style}
-      links={links && links.length > 0 && <FooterLinks links={links} />}
-      logo={logo && <FooterLogo logo={logo} />}
-      copyright={copyright && <FooterCopyright copyright={copyright} />}
-    />
-  )
-}
-
-export default React.memo(Footer)

www/apps/docs/src/theme/Layout/index.tsx

@@ -53,6 +53,7 @@ export default function Layout(props: Props): JSX.Element {
   return (
     <LayoutProvider>
       <PageMetadata title={title} description={description} />
+
       <SkipToContent />
 
       <Navbar />

www/apps/docs/src/theme/MDXComponents/A.tsx

@@ -1,13 +1,13 @@
 import React, { useMemo } from "react"
-import type { Props } from "@theme/MDXComponents/A"
 import { getGlossaryByPath } from "../../utils/glossary"
 import useDocusaurusContext from "@docusaurus/useDocusaurusContext"
 import { MedusaDocusaurusContext } from "@medusajs/docs"
 import Link from "@docusaurus/Link"
+import type { Props } from "@docusaurus/Link"
 import clsx from "clsx"
 import { Tooltip } from "docs-ui"
 
-const MDXA = (props: Props) => {
+const MDXA = (props: Omit<Props, "key">) => {
   const { href, children } = props
   const {
     siteConfig: { url },

www/apps/docs/src/theme/MDXComponents/Code.tsx

@@ -0,0 +1,17 @@
+import type { ComponentProps } from "react"
+import React from "react"
+import CodeBlock from "@theme/CodeBlock"
+import type { Props } from "@theme/MDXComponents/Code"
+import { InlineCode } from "docs-ui"
+
+export default function MDXCode(props: Omit<Props, "key">): JSX.Element {
+  const shouldBeInline = React.Children.toArray(props.children).every(
+    (el) => typeof el === "string" && !el.includes("\n")
+  )
+
+  return shouldBeInline ? (
+    <InlineCode {...props} />
+  ) : (
+    <CodeBlock {...(props as ComponentProps<typeof CodeBlock>)} />
+  )
+}

www/apps/docs/src/theme/MDXComponents/Details.tsx

@@ -1,23 +1,26 @@
 import React, { type ComponentProps, type ReactElement } from "react"
+import Details from "@theme/Details"
 import type { Props } from "@theme/MDXComponents/Details"
-import Details, { DetailsProps } from "../Details"
-import { type DetailsSummaryProps } from "docs-ui"
+import { DetailsSummary } from "docs-ui"
 
-type MDXDetailsProps = Props & DetailsProps
-
-export default function MDXDetails(props: MDXDetailsProps): JSX.Element {
+export default function MDXDetails(props: Omit<Props, "key">): JSX.Element {
   const items = React.Children.toArray(props.children)
   // Split summary item from the rest to pass it as a separate prop to the
   // Details theme component
   const summary = items.find(
-    (item): item is ReactElement<ComponentProps<"summary">> =>
-      React.isValidElement(item) &&
-      (item.props as { mdxType: string } | null)?.mdxType === "summary"
-  ) as React.ReactElement<DetailsSummaryProps>
+    (
+      item: ReactElement<ComponentProps<"summary">>
+    ): item is ReactElement<ComponentProps<"summary">> => {
+      return (
+        React.isValidElement(item) &&
+        (item.type === "summary" || item.type === DetailsSummary)
+      )
+    }
+  )
   const children = <>{items.filter((item) => item !== summary)}</>
 
   return (
-    <Details summary={summary} {...props}>
+    <Details {...props} summary={summary}>
       {children}
     </Details>
   )

www/apps/docs/src/theme/MDXComponents/H1.tsx

@@ -6,7 +6,7 @@ import { DocContextValue } from "@medusajs/docs"
 import { Badge, BadgeVariant } from "docs-ui"
 import clsx from "clsx"
 
-const H1 = ({ className, ...props }: Props) => {
+const H1 = ({ className, ...props }: Omit<Props, "key">) => {
   const {
     frontMatter: { badge },
   } = useDoc() as DocContextValue

www/apps/docs/src/theme/MDXComponents/index.tsx

@@ -1,18 +1,20 @@
 // Import the original mapper
 import MDXComponents from "@theme-original/MDXComponents"
 import CloudinaryImage from "@site/src/components/CloudinaryImage"
-import MDXDetails from "./Details"
 import MDXA from "./A"
-import { Kbd, DetailsSummary, InlineCode } from "docs-ui"
+import { Kbd, DetailsSummary } from "docs-ui"
 import H1 from "./H1"
+import MDXCode from "./Code"
+import MDXDetails from "./Details"
 
 export default {
   // Re-use the default mapping
   ...MDXComponents,
-  inlineCode: InlineCode,
+  code: MDXCode,
   img: CloudinaryImage,
   details: MDXDetails,
-  summary: DetailsSummary,
+  Details: MDXDetails,
+  Summary: DetailsSummary,
   a: MDXA,
   kbd: Kbd,
   h1: H1,

www/apps/docs/src/theme/MobileLogo/index.tsx

@@ -1,79 +0,0 @@
-import React from "react"
-import Link from "@docusaurus/Link"
-import useBaseUrl from "@docusaurus/useBaseUrl"
-import useDocusaurusContext from "@docusaurus/useDocusaurusContext"
-import { useThemeConfig, type NavbarLogo } from "@docusaurus/theme-common"
-import ThemedImage from "@theme/ThemedImage"
-import type { Props } from "@theme/Logo"
-import { ThemeConfig } from "@medusajs/docs"
-
-function LogoThemedImage({
-  logo,
-  alt,
-  imageClassName,
-}: {
-  logo: NavbarLogo
-  alt: string
-  imageClassName?: string
-}) {
-  const sources = {
-    light: useBaseUrl(logo.src),
-    dark: useBaseUrl(logo.srcDark || logo.src),
-  }
-  const themedImage = (
-    <ThemedImage
-      className={logo.className}
-      sources={sources}
-      height={logo.height}
-      width={logo.width}
-      alt={alt}
-      style={logo.style}
-    />
-  )
-
-  // Is this extra div really necessary?
-  // introduced in https://github.com/facebook/docusaurus/pull/5666
-  return imageClassName ? (
-    <div className={imageClassName}>{themedImage}</div>
-  ) : (
-    themedImage
-  )
-}
-
-export default function MobileLogo(props: Props): JSX.Element {
-  const {
-    siteConfig: { title },
-  } = useDocusaurusContext()
-  const {
-    navbar: { title: navbarTitle },
-    mobileLogo: logo,
-  } = useThemeConfig() as ThemeConfig
-
-  const { imageClassName, titleClassName, ...propsRest } = props
-  const logoLink = useBaseUrl(logo?.href || "/")
-
-  // If visible title is shown, fallback alt text should be
-  // an empty string to mark the logo as decorative.
-  const fallbackAlt = navbarTitle ? "" : title
-
-  // Use logo alt text if provided (including empty string),
-  // and provide a sensible fallback otherwise.
-  const alt = logo?.alt ?? fallbackAlt
-
-  return (
-    <Link
-      to={logoLink}
-      {...propsRest}
-      {...(logo?.target && { target: logo.target })}
-    >
-      {logo && (
-        <LogoThemedImage
-          logo={logo}
-          alt={alt}
-          imageClassName={imageClassName}
-        />
-      )}
-      {navbarTitle != null && <b className={titleClassName}>{navbarTitle}</b>}
-    </Link>
-  )
-}

www/apps/docs/src/theme/Navbar/Content/index.tsx

@@ -8,12 +8,12 @@ import NavbarItem, { type Props as NavbarItemConfig } from "@theme/NavbarItem"
 import NavbarColorModeToggle from "@theme/Navbar/ColorModeToggle"
 import NavbarMobileSidebarToggle from "@theme/Navbar/MobileSidebar/Toggle"
 import NavbarLogo from "@theme/Navbar/Logo"
-import NavbarActions from "../../../components/Navbar/Actions"
-import { ThemeConfig } from "@medusajs/docs"
-import useIsBrowser from "@docusaurus/useIsBrowser"
 import clsx from "clsx"
+import { ThemeConfig } from "@medusajs/docs"
 import { useSidebar } from "../../../providers/Sidebar"
+import useIsBrowser from "@docusaurus/useIsBrowser"
 import { Tooltip } from "docs-ui"
+import NavbarActions from "../../../components/Navbar/Actions"
 import { ChevronDoubleLeftMiniSolid, Sidebar } from "@medusajs/icons"
 
 function useNavbarItems() {

www/apps/docs/src/theme/Navbar/Logo/index.tsx

@@ -1,6 +1,6 @@
 import React from "react"
 import Logo from "@theme/Logo"
-import MobileLogo from "../../MobileLogo"
+import MobileLogo from "../../../components/MobileLogo"
 
 export default function NavbarLogo(): JSX.Element {
   return (

www/apps/docs/src/theme/Navbar/MobileSidebar/Header/index.tsx

@@ -1,5 +1,6 @@
 import React from "react"
 import { useNavbarMobileSidebar } from "@docusaurus/theme-common/internal"
+import { translate } from "@docusaurus/Translate"
 import NavbarColorModeToggle from "@theme/Navbar/ColorModeToggle"
 import IconClose from "@theme/Icon/Close"
 import NavbarLogo from "@theme/Navbar/Logo"
@@ -10,6 +11,11 @@ function CloseButton() {
   return (
     <button
       type="button"
+      aria-label={translate({
+        id: "theme.docs.sidebar.closeSidebarButtonAriaLabel",
+        message: "Close navigation bar",
+        description: "The ARIA label for close button of mobile sidebar",
+      })}
       className={clsx(
         "bg-transparent border-0 text-inherit cursor-pointer p-0",
         "flex ml-auto"
@@ -23,12 +29,7 @@ function CloseButton() {
 
 export default function NavbarMobileSidebarHeader(): JSX.Element {
   return (
-    <div
-      className={clsx(
-        "items-center shadow-navbar dark:shadow-navbar-dark",
-        "flex flex-1 h-navbar py-0.75 px-1.5"
-      )}
-    >
+    <div className="navbar-sidebar__brand">
       <NavbarLogo />
       <NavbarColorModeToggle
         className={clsx(

www/apps/docs/src/theme/NavbarItem/NavbarNavLink.tsx

@@ -13,7 +13,7 @@ export default function NavbarNavLink({
   html,
   prependBaseUrlToHref,
   ...props
-}: Props): JSX.Element {
+}: Omit<Props, "key">): JSX.Element {
   // TODO all this seems hacky
   // {to: 'version'} should probably be forbidden, in favor of {to: '/version'}
   const toUrl = useBaseUrl(to)

www/apps/docs/src/theme/NotFound.tsx

@@ -1,86 +0,0 @@
-import React from "react"
-import Translate, { translate } from "@docusaurus/Translate"
-import { PageMetadata } from "@docusaurus/theme-common"
-import Layout from "@theme/Layout"
-import useBaseUrl from "@docusaurus/useBaseUrl"
-import DocsProviders from "../providers/DocsProviders"
-
-export default function NotFound(): JSX.Element {
-  return (
-    <DocsProviders>
-      <PageMetadata
-        title={translate({
-          id: "theme.NotFound.title",
-          message: "Page Not Found",
-        })}
-      />
-      <Layout>
-        <main className="container markdown theme-doc-markdown my-4">
-          <div className="row">
-            <div className="col col--6 col--offset-3">
-              <h1>
-                <Translate
-                  id="theme.NotFound.title"
-                  description="The title of the 404 page"
-                >
-                  Page Not Found
-                </Translate>
-              </h1>
-              <p>
-                <Translate
-                  id="theme.NotFound.p1"
-                  description="The first paragraph of the 404 page"
-                >
-                  Looks like the page you&apos;re looking for has either changed
-                  into a different location or isn&apos;t in our documentation
-                  anymore.
-                </Translate>
-              </p>
-              <p>
-                If you think this is a mistake, please{" "}
-                <a
-                  href="https://github.com/medusajs/medusa/issues/new?assignees=&labels=type%3A+docs&template=docs.yml"
-                  rel="noopener noreferrer"
-                  target="_blank"
-                >
-                  report this issue on GitHub
-                </a>
-              </p>
-              <h2>Some popular links</h2>
-              <ul>
-                <li>
-                  <a href={useBaseUrl("/usage/create-medusa-app")}>
-                    Install Medusa with create-medusa-app
-                  </a>
-                </li>
-                <li>
-                  <a href="https://docs.medusajs.com/api/store">
-                    Storefront REST API Reference
-                  </a>
-                </li>
-                <li>
-                  <a href="https://docs.medusajs.com/api/admin">
-                    Admin REST API Reference
-                  </a>
-                </li>
-                <li>
-                  <a href={useBaseUrl("/starters/nextjs-medusa-starter")}>
-                    Install Next.js Storefront
-                  </a>
-                </li>
-                <li>
-                  <a href={useBaseUrl("/admin/quickstart")}>
-                    Install Medusa Admin
-                  </a>
-                </li>
-                <li>
-                  <a href={useBaseUrl("/user-guide")}>User Guide</a>
-                </li>
-              </ul>
-            </div>
-          </div>
-        </main>
-      </Layout>
-    </DocsProviders>
-  )
-}

www/apps/docs/src/theme/NotFound/Content/index.tsx

@@ -0,0 +1,75 @@
+import React from "react"
+import clsx from "clsx"
+import Translate from "@docusaurus/Translate"
+import type { Props } from "@theme/NotFound/Content"
+import useBaseUrl from "@docusaurus/useBaseUrl"
+
+export default function NotFoundContent({ className }: Props): JSX.Element {
+  return (
+    <main
+      className={clsx("container markdown theme-doc-markdown my-4", className)}
+    >
+      <div className="row">
+        <div className="col col--6 col--offset-3">
+          <h1>
+            <Translate
+              id="theme.NotFound.title"
+              description="The title of the 404 page"
+            >
+              Page Not Found
+            </Translate>
+          </h1>
+          <p>
+            <Translate
+              id="theme.NotFound.p1"
+              description="The first paragraph of the 404 page"
+            >
+              Looks like the page you&apos;re looking for has either changed
+              into a different location or isn&apos;t in our documentation
+              anymore.
+            </Translate>
+          </p>
+          <p>
+            If you think this is a mistake, please{" "}
+            <a
+              href="https://github.com/medusajs/medusa/issues/new?assignees=&labels=type%3A+docs&template=docs.yml"
+              rel="noopener noreferrer"
+              target="_blank"
+            >
+              report this issue on GitHub
+            </a>
+          </p>
+          <h2>Some popular links</h2>
+          <ul>
+            <li>
+              <a href={useBaseUrl("/usage/create-medusa-app")}>
+                Install Medusa with create-medusa-app
+              </a>
+            </li>
+            <li>
+              <a href="https://docs.medusajs.com/api/store">
+                Storefront REST API Reference
+              </a>
+            </li>
+            <li>
+              <a href="https://docs.medusajs.com/api/admin">
+                Admin REST API Reference
+              </a>
+            </li>
+            <li>
+              <a href={useBaseUrl("/starters/nextjs-medusa-starter")}>
+                Install Next.js Storefront
+              </a>
+            </li>
+            <li>
+              <a href={useBaseUrl("/admin/quickstart")}>Install Medusa Admin</a>
+            </li>
+            <li>
+              <a href={useBaseUrl("/user-guide")}>User Guide</a>
+            </li>
+          </ul>
+        </div>
+      </div>
+    </main>
+  )
+}

www/apps/docs/src/theme/NotFound/index.tsx

@@ -0,0 +1,21 @@
+import React from "react"
+import { translate } from "@docusaurus/Translate"
+import { PageMetadata } from "@docusaurus/theme-common"
+import Layout from "@theme/Layout"
+import NotFoundContent from "@theme/NotFound/Content"
+import DocsProviders from "../../providers/DocsProviders"
+
+export default function Index(): JSX.Element {
+  const title = translate({
+    id: "theme.NotFound.title",
+    message: "Page Not Found",
+  })
+  return (
+    <DocsProviders>
+      <PageMetadata title={title} />
+      <Layout>
+        <NotFoundContent />
+      </Layout>
+    </DocsProviders>
+  )
+}

www/apps/docs/src/theme/TOCItems/index.tsx

@@ -2,9 +2,9 @@ import React from "react"
 import TOCItems from "@theme-original/TOCItems"
 import type TOCItemsType from "@theme/TOCItems"
 import type { WrapperProps } from "@docusaurus/types"
-import StructuredDataHowTo from "@site/src/components/StructuredData/HowTo"
 import { useDoc } from "@docusaurus/theme-common/internal"
 import { DocContextValue } from "@medusajs/docs"
+import StructuredDataHowTo from "../../components/StructuredData/HowTo"
 
 type Props = WrapperProps<typeof TOCItemsType>
 

www/apps/docs/src/theme/Tabs/index.tsx

@@ -1,13 +1,18 @@
-import React, { ReactElement, cloneElement, useEffect, useRef } from "react"
+import React, {
+  cloneElement,
+  useRef,
+  type ReactElement,
+  useEffect,
+} from "react"
 import clsx from "clsx"
 import {
   useScrollPositionBlocker,
   useTabs,
+  sanitizeTabsChildren,
   type TabItemProps,
 } from "@docusaurus/theme-common/internal"
 import useIsBrowser from "@docusaurus/useIsBrowser"
 import type { Props as OldProps } from "@theme/Tabs"
-// import styles from "./styles.module.css"
 
 type TabsCustomProps = {
   isCodeTabs?: boolean
@@ -16,6 +21,13 @@ type TabsCustomProps = {
 
 type TabListProps = OldProps & ReturnType<typeof useTabs> & TabsCustomProps
 
+type TabsComponentProp = TabsCustomProps & OldProps
+
+type TabsProps = {
+  wrapperClassName?: string
+  isCodeTabs?: boolean
+} & OldProps
+
 function TabList({
   className,
   selectedValue,
@@ -29,6 +41,7 @@ function TabList({
     useScrollPositionBlocker()
   const codeTabSelectorRef = useRef(null)
   const codeTabsWrapperRef = useRef(null)
+
   const handleTabChange = (
     event:
       | React.FocusEvent<HTMLLIElement>
@@ -206,8 +219,6 @@ function TabContent({
   )
 }
 
-type TabsComponentProp = TabsCustomProps & OldProps
-
 function TabsComponent(props: TabsComponentProp): JSX.Element {
   const tabs = useTabs(props)
   return (
@@ -218,11 +229,6 @@ function TabsComponent(props: TabsComponentProp): JSX.Element {
   )
 }
 
-type TabsProps = {
-  wrapperClassName?: string
-  isCodeTabs?: boolean
-} & OldProps
-
 function checkCodeTabs(props: TabsProps): boolean {
   return props.groupId === "npm2yarn" || props.isCodeTabs
 }
@@ -255,7 +261,9 @@ export default function Tabs(props: TabsProps): JSX.Element {
         key={String(isBrowser)}
         isCodeTabs={isCodeTabs}
         {...props}
-      />
+      >
+        {sanitizeTabsChildren(props.children)}
+      </TabsComponent>
     </div>
   )
 }