docs: preparations for preview (#7267)

* configured base paths + added development banner

* fix typelist site url

* added navbar and sidebar badges

* configure algolia filters

* remove AI assistant

* remove unused imports

* change navbar text and badge

* lint fixes

* fix build error

* add to api reference rewrites

* fix build error

* fix build errors in user-guide

* fix feedback component

* add parent title to pagination

* added breadcrumbs component

* remove user-guide links

* resolve todos

* fix details about authentication

* change documentation title

* lint content

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

@@ -0,0 +1,15 @@
+import React from "react"
+import { Card, Link } from "../.."
+
+export const Bannerv2 = () => {
+  return (
+    <Card>
+      This documentation is for Medusa v2, which isn&apos;t ready for
+      production.
+      <br />
+      <br />
+      For production-use, refer to{" "}
+      <Link href="https://docs.medusajs.com">this documentation</Link> instead.
+    </Card>
+  )
+}

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

@@ -0,0 +1,76 @@
+"use client"
+
+import React, { useMemo } from "react"
+import { CurrentItemsState, useSidebar } from "@/providers"
+import { TriangleRightMini } from "@medusajs/icons"
+import Link from "next/link"
+import clsx from "clsx"
+
+type BreadcrumbItem = Map<string, string>
+
+export const Breadcrumbs = () => {
+  const { currentItems } = useSidebar()
+
+  const getBreadcrumbsOfItem = (item: CurrentItemsState): BreadcrumbItem => {
+    let tempBreadcrumbItems: BreadcrumbItem = new Map()
+    if (item.previousSidebar) {
+      tempBreadcrumbItems = getBreadcrumbsOfItem(item.previousSidebar)
+    }
+
+    tempBreadcrumbItems.set(
+      item.parentItem?.path || item.top[0].path || "/",
+      item.parentItem?.childSidebarTitle || item.parentItem?.title || ""
+    )
+
+    return tempBreadcrumbItems
+  }
+
+  const breadcrumbItems = useMemo(() => {
+    const tempBreadcrumbItems: BreadcrumbItem = new Map()
+    if (!currentItems) {
+      return tempBreadcrumbItems
+    }
+
+    tempBreadcrumbItems.set("/", "Home")
+
+    getBreadcrumbsOfItem(currentItems).forEach((value, key) =>
+      tempBreadcrumbItems.set(key, value)
+    )
+
+    return tempBreadcrumbItems
+  }, [currentItems])
+
+  const getBreadcrumbItemElms = (): React.ReactNode[] => {
+    const elms: React.ReactNode[] = []
+    breadcrumbItems.forEach((title, path) => {
+      elms.push(
+        <React.Fragment key={path}>
+          {elms.length !== 0 && (
+            <TriangleRightMini className={clsx("text-medusa-fg-muted")} />
+          )}
+          <Link
+            href={path}
+            className={clsx(
+              "text-compact-x-small-plus text-medusa-fg-muted",
+              "hover:text-medusa-fg-subtle transition-colors"
+            )}
+          >
+            {title}
+          </Link>
+        </React.Fragment>
+      )
+    })
+
+    return elms
+  }
+
+  return (
+    <>
+      {breadcrumbItems.size > 0 && (
+        <div className="flex gap-docs_0.25 items-center mb-docs_1">
+          {...getBreadcrumbItemElms()}
+        </div>
+      )}
+    </>
+  )
+}

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

@@ -2,7 +2,7 @@
 
 import React from "react"
 import clsx from "clsx"
-import { Link, LinkProps } from "@/components"
+import { Badge, BadgeProps, Link, LinkProps } from "@/components"
 
 export type NavbarLinkProps = {
   href: string
@@ -10,6 +10,7 @@ export type NavbarLinkProps = {
   className?: string
   activeValuePattern?: RegExp
   isActive?: boolean
+  badge?: BadgeProps
 } & LinkProps
 
 export const NavbarLink = ({
@@ -17,6 +18,7 @@ export const NavbarLink = ({
   label,
   className,
   isActive,
+  badge
 }: NavbarLinkProps) => {
   return (
     <Link
@@ -30,6 +32,10 @@ export const NavbarLink = ({
       )}
     >
       {label}
+      {badge && <Badge {...badge} className={clsx(
+        badge.className,
+        "ml-docs_0.5"
+      )} />}
     </Link>
   )
 }

www/packages/docs-ui/src/components/Navbar/Logo/index.tsx

@@ -4,6 +4,7 @@ import React from "react"
 import { useColorMode } from "@/providers"
 import Link from "next/link"
 import clsx from "clsx"
+import Image from "next/image"
 
 export type NavbarLogoProps = {
   light: string
@@ -22,7 +23,7 @@ export const NavbarLogo = ({
 
   return (
     <Link href={`/`} className={clsx("flex-1", className)}>
-      <img
+      <Image
         src={colorMode === "light" ? light : dark || light}
         alt="Medusa Logo"
         height={20}

www/packages/docs-ui/src/components/Navbar/NavbarDivider/index.tsx

@@ -0,0 +1,11 @@
+import clsx from "clsx"
+import React from "react"
+
+export const NavbarDivider = () => {
+  return (
+    <div className={clsx(
+      "w-px h-1/2 bg-medusa-fg-disabled",
+      "mx-docs_0.5"
+    )}></div>
+  )
+}

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

@@ -6,10 +6,19 @@ import { NavbarLogo, NavbarLogoProps } from "./Logo"
 import { NavbarMobileMenu } from "./MobileMenu"
 import { NavbarSearchModalOpener } from "./SearchModalOpener"
 import { NavbarMobileMenuButtonProps } from "./MobileMenu/Button"
+import { NavbarDivider } from "./NavbarDivider"
+
+export type NavbarItem = {
+  type: "link"
+  props: NavbarLinkProps
+} | {
+  type: "divider"
+  props?: {}
+}
 
 export type NavbarProps = {
   logo: NavbarLogoProps
-  items: NavbarLinkProps[]
+  items: NavbarItem[]
   showSearchOpener?: boolean
   showColorModeToggle?: boolean
   additionalActionsAfter?: React.ReactNode
@@ -45,9 +54,14 @@ export const Navbar = ({
       >
         <div className="hidden w-full items-center gap-docs_0.5 lg:flex lg:w-auto lg:gap-docs_1.5">
           <NavbarLogo {...logo} />
-          {items.map((item, index) => (
-            <NavbarLink key={index} {...item} />
-          ))}
+          {items.map(({type, props}, index) => {
+            switch(type) {
+              case "divider":
+                return <NavbarDivider key={index}  />
+              default:
+                return <NavbarLink key={index} {...props} />
+            }
+          })}
         </div>
         <div className="hidden min-w-0 flex-1 items-center justify-end gap-docs_0.5 lg:flex">
           {additionalActionsBefore}

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

@@ -13,6 +13,7 @@ export const Pagination = () => {
       {previousPage && (
         <Card
           title={previousPage.title}
+          text={previousPage.parentTitle}
           startIcon={<ChevronLeft />}
           showLinkIcon={false}
           href={previousPage.link}
@@ -22,6 +23,7 @@ export const Pagination = () => {
       {nextPage && (
         <Card
           title={nextPage.title}
+          text={nextPage.parentTitle}
           endIcon={<ChevronRight />}
           showLinkIcon={false}
           href={nextPage.link}

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

@@ -85,6 +85,9 @@ export const Search = ({
       <InstantSearch
         indexName={algolia.mainIndexName}
         searchClient={searchClient}
+        future={{
+          preserveSharedStateOnUnmount: true
+        }}
       >
         <div className={clsx("bg-medusa-bg-base flex")}>
           <SearchBox

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

@@ -11,7 +11,7 @@ export const SidebarBack = () => {
   return (
     <div
       className={clsx(
-        "my-docs_1.5 cursor-pointer",
+        "mb-docs_1.5 cursor-pointer",
         "flex items-center gap-docs_0.5 rounded-docs_sm px-docs_0.5 py-[6px] hover:no-underline",
         "border border-transparent",
         "text-medusa-fg-subtle text-medium-plus"

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

@@ -16,6 +16,8 @@ export type SidebarItemProps = {
   expandItems?: boolean
   currentLevel?: number
   isSidebarTitle?: boolean
+  sidebarHasParent?: boolean
+  isMobile?: boolean
 } & React.AllHTMLAttributes<HTMLLIElement>
 
 export const SidebarItem = ({
@@ -24,6 +26,8 @@ export const SidebarItem = ({
   expandItems = false,
   className,
   currentLevel = 1,
+  sidebarHasParent = false,
+  isMobile = false
 }: SidebarItemProps) => {
   const [showLoading, setShowLoading] = useState(false)
   const {
@@ -34,8 +38,8 @@ export const SidebarItem = ({
     sidebarRef,
   } = useSidebar()
   const active = useMemo(
-    () => isItemActive(item, nested),
-    [isItemActive, item, nested]
+    () => !isMobile && isItemActive(item, nested),
+    [isItemActive, item, nested, isMobile]
   )
   const collapsed = !expandItems && !isItemActive(item, true)
   const ref = useRef<HTMLLIElement>(null)
@@ -131,7 +135,11 @@ export const SidebarItem = ({
   return (
     <li
       className={clsx(
-        canHaveTitleStyling && !collapsed && "my-docs_1.5",
+        canHaveTitleStyling &&
+          !collapsed && [
+            !sidebarHasParent && "my-docs_1.5",
+            sidebarHasParent && "[&:not(:first-child)]:my-docs_1.5",
+          ],
         !canHaveTitleStyling &&
           !nested &&
           active &&

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

@@ -11,9 +11,9 @@ export const SidebarTitle = ({ item }: SidebarTitleProps) => {
   return (
     <Link
       className={clsx(
-        "flex items-center justify-between gap-docs_0.5 rounded-docs_sm px-docs_0.5 py-[6px] hover:no-underline",
+        "flex items-center justify-between gap-docs_0.5 rounded-docs_sm px-docs_0.5 pb-[6px] hover:no-underline",
         "border border-transparent",
-        "text-medusa-fg-subtle text-medium-plus"
+        "text-medusa-fg-subtle text-large-plus"
       )}
       href={item.isPathHref && item.path ? item.path : `#${item.path}`}
       replace={!item.isPathHref}

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

@@ -1,6 +1,6 @@
 "use client"
 
-import React, { useMemo } from "react"
+import React, { useMemo, useRef } from "react"
 import { useSidebar } from "@/providers"
 import clsx from "clsx"
 import { Loading } from "@/components"
@@ -12,11 +12,13 @@ import { CSSTransition, SwitchTransition } from "react-transition-group"
 export type SidebarProps = {
   className?: string
   expandItems?: boolean
+  banner?: React.ReactNode
 }
 
 export const Sidebar = ({
   className = "",
   expandItems = false,
+  banner,
 }: SidebarProps) => {
   const {
     items,
@@ -32,6 +34,11 @@ export const Sidebar = ({
     [items, currentItems]
   )
 
+  const sidebarHasParent = useMemo(
+    () => sidebarItems.parentItem !== undefined,
+    [sidebarItems]
+  )
+
   return (
     <aside
       className={clsx(
@@ -47,69 +54,76 @@ export const Sidebar = ({
         animationFillMode: "forwards",
       }}
     >
-      <SwitchTransition>
-        <CSSTransition
-          key={sidebarItems.parentItem?.title || "home"}
-          nodeRef={sidebarRef}
-          classNames={{
-            enter: "animate-fadeInLeft animate-fast",
-            exit: "animate-fadeOutLeft animate-fast",
-          }}
-          timeout={200}
-        >
-          <ul
-            className={clsx(
-              "sticky top-0 h-screen max-h-screen w-full list-none overflow-auto p-0",
-              "px-docs_1.5 pb-[57px] pt-docs_1.5"
-            )}
-            id="sidebar"
-            ref={sidebarRef}
+      <ul
+        className={clsx(
+          "sticky top-0 h-screen max-h-screen w-full list-none p-0",
+          "px-docs_1.5 pb-[57px] pt-docs_1.5",
+          "flex flex-col"
+        )}
+        id="sidebar"
+      >
+        {banner && <div className="mb-docs_1">{banner}</div>}
+        {sidebarItems.parentItem && (
+          <div className={clsx("mb-docs_1", !banner && "mt-docs_1.5")}>
+            <SidebarBack />
+            <SidebarTitle item={sidebarItems.parentItem} />
+          </div>
+        )}
+        <SwitchTransition>
+          <CSSTransition
+            key={sidebarItems.parentItem?.title || "home"}
+            nodeRef={sidebarRef}
+            classNames={{
+              enter: "animate-fadeInLeft animate-fast",
+              exit: "animate-fadeOutLeft animate-fast",
+            }}
+            timeout={200}
           >
-            {sidebarItems.parentItem && (
-              <>
-                <SidebarBack />
-                <SidebarTitle item={sidebarItems.parentItem} />
-              </>
-            )}
-            <div className="mb-docs_1.5 lg:hidden">
-              {!sidebarItems.mobile.length && !staticSidebarItems && (
-                <Loading className="px-0" />
-              )}
-              {sidebarItems.mobile.map((item, index) => (
-                <SidebarItem
-                  item={item}
-                  key={index}
-                  expandItems={expandItems}
-                />
-              ))}
+            <div className="overflow-auto" ref={sidebarRef}>
+              <div className={clsx("mb-docs_1.5 lg:hidden")}>
+                {!sidebarItems.mobile.length && !staticSidebarItems && (
+                  <Loading className="px-0" />
+                )}
+                {sidebarItems.mobile.map((item, index) => (
+                  <SidebarItem
+                    item={item}
+                    key={index}
+                    expandItems={expandItems}
+                    sidebarHasParent={sidebarHasParent}
+                    isMobile={true}
+                  />
+                ))}
+              </div>
+              <div className={clsx("mb-docs_1.5")}>
+                {!sidebarItems.top.length && !staticSidebarItems && (
+                  <Loading className="px-0" />
+                )}
+                {sidebarItems.top.map((item, index) => (
+                  <SidebarItem
+                    item={item}
+                    key={index}
+                    expandItems={expandItems}
+                    sidebarHasParent={sidebarHasParent}
+                  />
+                ))}
+              </div>
+              <div className="mb-docs_1.5">
+                {!sidebarItems.bottom.length && !staticSidebarItems && (
+                  <Loading className="px-0" />
+                )}
+                {sidebarItems.bottom.map((item, index) => (
+                  <SidebarItem
+                    item={item}
+                    key={index}
+                    expandItems={expandItems}
+                    sidebarHasParent={sidebarHasParent}
+                  />
+                ))}
+              </div>
             </div>
-            <div className="mb-docs_1.5">
-              {!sidebarItems.top.length && !staticSidebarItems && (
-                <Loading className="px-0" />
-              )}
-              {sidebarItems.top.map((item, index) => (
-                <SidebarItem
-                  item={item}
-                  key={index}
-                  expandItems={expandItems}
-                />
-              ))}
-            </div>
-            <div className="mb-docs_1.5">
-              {!sidebarItems.bottom.length && !staticSidebarItems && (
-                <Loading className="px-0" />
-              )}
-              {sidebarItems.bottom.map((item, index) => (
-                <SidebarItem
-                  item={item}
-                  key={index}
-                  expandItems={expandItems}
-                />
-              ))}
-            </div>
-          </ul>
-        </CSSTransition>
-      </SwitchTransition>
+          </CSSTransition>
+        </SwitchTransition>
+      </ul>
     </aside>
   )
 }

www/packages/docs-ui/src/components/TypeList/Items/index.tsx

@@ -21,7 +21,7 @@ import {
 } from "@medusajs/icons"
 import { decodeStr, isInView } from "@/utils"
 import { usePathname } from "next/navigation"
-import { useIsBrowser } from "../../.."
+import { useIsBrowser, useSiteConfig } from "../../.."
 
 type CommonProps = ParentCommonProps & {
   level?: number
@@ -39,10 +39,11 @@ const TypeListItem = ({
   expandUrl,
   elementKey,
   sectionTitle,
-  siteUrl = "",
 }: TypeListItemProps) => {
   const isBrowser = useIsBrowser()
   const pathname = usePathname()
+  const { config: { baseUrl, basePath } } = useSiteConfig()
+  const siteUrl = `${baseUrl}${basePath}`
 
   const groupName = useMemo(() => {
     switch (level) {

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

@@ -5,7 +5,6 @@ import { Loading } from "@/components"
 export type CommonProps = {
   expandUrl?: string
   sectionTitle?: string
-  siteUrl?: string
 }
 
 export type Type = {
@@ -30,7 +29,6 @@ const TypeListItems = lazy(async () => import("./Items"))
 export const TypeList = ({
   types,
   className,
-  siteUrl,
   sectionTitle,
   expandUrl,
   ...props
@@ -48,7 +46,6 @@ export const TypeList = ({
           types={types}
           expandUrl={expandUrl}
           sectionTitle={sectionTitle}
-          siteUrl={siteUrl}
         />
       </Suspense>
     </div>

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

@@ -1,8 +1,10 @@
 export * from "./AiAssistant"
 export * from "./AiAssistant/CommandIcon"
 export * from "./Badge"
+export * from "./Bannerv2"
 export * from "./Bordered"
 export * from "./BorderedIcon"
+export * from "./Breadcrumbs"
 export * from "./Button"
 export * from "./Card"
 export * from "./CardList"

www/packages/docs-ui/src/constants.ts

@@ -1,198 +0,0 @@
-import { NavbarLinkProps } from "@/components"
-import { OptionType } from "./hooks"
-import { SidebarItemType } from "types"
-
-export const GITHUB_ISSUES_PREFIX = `https://github.com/medusajs/medusa/issues/new?assignees=&labels=type%3A+docs&template=docs.yml`
-export const GITHUB_UI_ISSUES_PREFIX = `https://github.com/medusajs/ui/issues/new?labels=documentation`
-
-export const navbarItems: NavbarLinkProps[] = [
-  {
-    label: "Docs",
-    target: "_blank",
-    rel: "noreferrer",
-    href: `/`,
-  },
-  {
-    label: "Resources",
-    target: "_blank",
-    rel: "noreferrer",
-    href: `/resources`,
-  },
-  {
-    label: "User Guide",
-    target: "_blank",
-    rel: "noreferrer",
-    href: `/user-guide`,
-  },
-  {
-    label: "Store API",
-    target: "_blank",
-    rel: "noreferrer",
-    href: `/api/store`,
-  },
-  {
-    label: "Admin API",
-    target: "_blank",
-    rel: "noreferrer",
-    href: `/api/admin`,
-  },
-  {
-    label: "UI",
-    target: "_blank",
-    rel: "noreferrer",
-    href: `/ui`,
-  },
-]
-
-/** 
- * TODO Uncomment for V2
- * 
- * export const navbarItems: NavbarLinkProps[] = [
-  {
-    label: "Docs",
-    target: "_blank",
-    rel: "noreferrer",
-    href: `/`,
-    activeValuePattern: /^\/(?!api\/|ui\/|user-guide\/|resources\/)/,
-  },
-  {
-    label: "User Guide",
-    target: "_blank",
-    rel: "noreferrer",
-    href: `/user-guide`,
-  },
-  {
-    label: "Store API",
-    target: "_blank",
-    rel: "noreferrer",
-    href: `/api/store`,
-  },
-  {
-    label: "Admin API",
-    target: "_blank",
-    rel: "noreferrer",
-    href: `/api/admin`,
-  },
-  {
-    label: "UI",
-    target: "_blank",
-    rel: "noreferrer",
-    href: `/ui`,
-    activeValuePattern: /^\/ui\//,
-  },
-  {
-    label: "V2 Docs",
-    target: "_blank",
-    rel: "noreferrer",
-    href: `/v2`,
-  },
-]
-
-export const navbarItemsV2: NavbarLinkProps[] = [
-  {
-    label: "Docs",
-    target: "_blank",
-    rel: "noreferrer",
-    href: `/v2`,
-    activeValuePattern: /^\/v2\/(?!api\/|ui\/|user-guide\/|resources\/)/,
-  },
-  {
-    label: "Resources",
-    target: "_blank",
-    rel: "noreferrer",
-    href: `/v2/resources`,
-    activeValuePattern: /^\/v2\/resources\//,
-  },
-  {
-    label: "User Guide",
-    target: "_blank",
-    rel: "noreferrer",
-    href: `/v2/user-guide`,
-    activeValuePattern: /^\/v2\/user-guide/,
-  },
-  {
-    label: "Store API",
-    target: "_blank",
-    rel: "noreferrer",
-    href: `/api/store`,
-  },
-  {
-    label: "Admin API",
-    target: "_blank",
-    rel: "noreferrer",
-    href: `/api/admin`,
-  },
-  {
-    label: "UI",
-    target: "_blank",
-    rel: "noreferrer",
-    href: `/ui`,
-    activeValuePattern: /^\/ui\//,
-  },
-]
- */
-
-export const mobileSidebarItems: SidebarItemType[] = [
-  {
-    title: "Docs",
-    path: `/`,
-    loaded: true,
-    isPathHref: true,
-  },
-  {
-    title: "User Guide",
-    path: `/user-guide`,
-    loaded: true,
-    isPathHref: true,
-  },
-  {
-    title: "Store API",
-    path: `/api/store`,
-    loaded: true,
-    isPathHref: true,
-  },
-  {
-    title: "Admin API",
-    path: `/api/admin`,
-    loaded: true,
-    isPathHref: true,
-  },
-  {
-    title: "UI",
-    path: `/ui`,
-    loaded: true,
-    isPathHref: true,
-  },
-]
-
-// TODO add resources once we create index
-export const searchFilters: OptionType[] = [
-  {
-    value: "admin",
-    label: "Admin API",
-  },
-  {
-    value: "store",
-    label: "Store API",
-  },
-  {
-    value: "docs",
-    label: "Docs",
-  },
-  {
-    value: "user-guide",
-    label: "User Guide",
-  },
-  {
-    value: "plugins",
-    label: "Plugins",
-  },
-  {
-    value: "reference",
-    label: "References",
-  },
-  {
-    value: "ui",
-    label: "UI",
-  },
-]

www/packages/docs-ui/src/constants.tsx

@@ -0,0 +1,368 @@
+import React from "react"
+import { Badge, NavbarItem } from "@/components"
+import { OptionType } from "./hooks"
+import { SidebarItemType } from "types"
+
+export const GITHUB_ISSUES_PREFIX = `https://github.com/medusajs/medusa/issues/new?assignees=&labels=type%3A+docs&template=docs.yml`
+export const GITHUB_UI_ISSUES_PREFIX = `https://github.com/medusajs/ui/issues/new?labels=documentation`
+
+export const navbarItemsV1: NavbarItem[] = [
+  {
+    type: "link",
+    props: {
+      label: "Docs",
+      target: "_blank",
+      rel: "noreferrer",
+      href: `/`,
+    },
+  },
+  {
+    type: "link",
+    props: {
+      label: "User Guide",
+      target: "_blank",
+      rel: "noreferrer",
+      href: `/user-guide`,
+    },
+  },
+  {
+    type: "link",
+    props: {
+      label: "Store API",
+      target: "_blank",
+      rel: "noreferrer",
+      href: `/api/store`,
+    },
+  },
+  {
+    type: "link",
+    props: {
+      label: "Admin API",
+      target: "_blank",
+      rel: "noreferrer",
+      href: `/api/admin`,
+    },
+  },
+  {
+    type: "link",
+    props: {
+      label: "UI",
+      target: "_blank",
+      rel: "noreferrer",
+      href: `/ui`,
+    },
+  },
+  {
+    type: "divider",
+  },
+  {
+    type: "link",
+    props: {
+      label: "Learn Medusa v2",
+      target: "_blank",
+      rel: "noreferrer",
+      href: `/v2`,
+      badge: {
+        variant: "blue",
+        children: "New",
+      },
+    },
+  },
+]
+
+export const navbarItemsV2: NavbarItem[] = [
+  {
+    type: "link",
+    props: {
+      label: "Docs",
+      target: "_blank",
+      rel: "noreferrer",
+      href: `/v2`,
+    },
+  },
+  {
+    type: "link",
+    props: {
+      label: "Learning Resources",
+      target: "_blank",
+      rel: "noreferrer",
+      href: `/v2/resources`,
+    },
+  },
+  {
+    type: "divider",
+  },
+  {
+    type: "link",
+    props: {
+      label: "Docs",
+      target: "_blank",
+      rel: "noreferrer",
+      href: `/`,
+      badge: {
+        variant: "neutral",
+        children: "v1",
+      },
+    },
+  },
+  {
+    type: "link",
+    props: {
+      label: "User Guide",
+      target: "_blank",
+      rel: "noreferrer",
+      href: `/user-guide`,
+      badge: {
+        variant: "neutral",
+        children: "v1",
+      },
+    },
+  },
+  {
+    type: "link",
+    props: {
+      label: "Store API",
+      target: "_blank",
+      rel: "noreferrer",
+      href: `/api/store`,
+    },
+  },
+  {
+    type: "link",
+    props: {
+      label: "Admin API",
+      target: "_blank",
+      rel: "noreferrer",
+      href: `/api/admin`,
+    },
+  },
+  {
+    type: "link",
+    props: {
+      label: "UI",
+      target: "_blank",
+      rel: "noreferrer",
+      href: `/ui`,
+    },
+  },
+]
+
+export const legacyNavbarItems: NavbarItem[] = [
+  {
+    type: "link",
+    props: {
+      label: "Docs",
+      target: "_blank",
+      rel: "noreferrer",
+      href: `/`,
+    },
+  },
+  {
+    type: "link",
+    props: {
+      label: "Resources",
+      target: "_blank",
+      rel: "noreferrer",
+      href: `/resources`,
+    },
+  },
+  {
+    type: "link",
+    props: {
+      label: "User Guide",
+      target: "_blank",
+      rel: "noreferrer",
+      href: `/user-guide`,
+    },
+  },
+  {
+    type: "link",
+    props: {
+      label: "Store API",
+      target: "_blank",
+      rel: "noreferrer",
+      href: `/api/store`,
+    },
+  },
+  {
+    type: "link",
+    props: {
+      label: "Admin API",
+      target: "_blank",
+      rel: "noreferrer",
+      href: `/api/admin`,
+    },
+  },
+  {
+    type: "link",
+    props: {
+      label: "UI",
+      target: "_blank",
+      rel: "noreferrer",
+      href: `/ui`,
+    },
+  },
+]
+
+export const mobileSidebarItemsV1: SidebarItemType[] = [
+  {
+    title: "Docs",
+    path: `/`,
+    loaded: true,
+    isPathHref: true,
+  },
+  {
+    title: "User Guide",
+    path: `/user-guide`,
+    loaded: true,
+    isPathHref: true,
+  },
+  {
+    title: "Store API",
+    path: `/api/store`,
+    loaded: true,
+    isPathHref: true,
+  },
+  {
+    title: "Admin API",
+    path: `/api/admin`,
+    loaded: true,
+    isPathHref: true,
+  },
+  {
+    title: "UI",
+    path: `/ui`,
+    loaded: true,
+    isPathHref: true,
+  },
+  {
+    title: "Book",
+    path: `/v2`,
+    loaded: true,
+    isPathHref: true,
+    additionalElms: <Badge variant="blue">v2</Badge>,
+  },
+]
+
+export const mobileSidebarItemsV2: SidebarItemType[] = [
+  {
+    title: "Book",
+    path: `/v2`,
+    loaded: true,
+    isPathHref: true,
+  },
+  {
+    title: "Learning Resources",
+    path: `/v2/resources`,
+    loaded: true,
+    isPathHref: true,
+  },
+  {
+    title: "Docs",
+    path: `/`,
+    loaded: true,
+    isPathHref: true,
+    additionalElms: <Badge variant="neutral">v1</Badge>,
+  },
+  {
+    title: "User Guide",
+    path: `/user-guide`,
+    loaded: true,
+    isPathHref: true,
+    additionalElms: <Badge variant="neutral">v1</Badge>,
+  },
+  {
+    title: "Store API",
+    path: `/api/store`,
+    loaded: true,
+    isPathHref: true,
+  },
+  {
+    title: "Admin API",
+    path: `/api/admin`,
+    loaded: true,
+    isPathHref: true,
+  },
+  {
+    title: "UI",
+    path: `/ui`,
+    loaded: true,
+    isPathHref: true,
+  },
+]
+
+export const legacyMobileSidebarItems: SidebarItemType[] = [
+  {
+    title: "Docs",
+    path: `/`,
+    loaded: true,
+    isPathHref: true,
+  },
+  {
+    title: "User Guide",
+    path: `/user-guide`,
+    loaded: true,
+    isPathHref: true,
+  },
+  {
+    title: "Store API",
+    path: `/api/store`,
+    loaded: true,
+    isPathHref: true,
+  },
+  {
+    title: "Admin API",
+    path: `/api/admin`,
+    loaded: true,
+    isPathHref: true,
+  },
+  {
+    title: "UI",
+    path: `/ui`,
+    loaded: true,
+    isPathHref: true,
+  },
+]
+
+export const searchFiltersV2: OptionType[] = [
+  {
+    value: "book",
+    label: "Book",
+  },
+  {
+    value: "resources",
+    label: "Resources",
+  },
+  // TODO add more filters once V2 become the main docs
+]
+
+export const searchFiltersV1: OptionType[] = [
+  {
+    value: "admin",
+    label: "Admin API",
+  },
+  {
+    value: "store",
+    label: "Store API",
+  },
+  {
+    value: "docs",
+    label: "Docs",
+  },
+  {
+    value: "user-guide",
+    label: "User Guide",
+  },
+  {
+    value: "plugins",
+    label: "Plugins",
+  },
+  {
+    value: "reference",
+    label: "References",
+  },
+  {
+    value: "ui",
+    label: "UI",
+  },
+]

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

@@ -14,6 +14,7 @@ import { SidebarItemType } from "types"
 export type Page = {
   title: string
   description?: string
+  parentTitle?: string
   link: string
 }
 
@@ -26,10 +27,14 @@ export const PaginationContext = createContext<PaginationContextType | null>(
   null
 )
 
+type SidebarItemWithParent = SidebarItemType & {
+  parent?: SidebarItemType
+}
+
 type SearchItemsResult = {
   foundActive: boolean
-  prevItem?: SidebarItemType
-  nextItem?: SidebarItemType
+  prevItem?: SidebarItemWithParent
+  nextItem?: SidebarItemWithParent
 }
 
 export type PaginationProviderProps = {
@@ -66,14 +71,20 @@ export const PaginationProvider = ({ children }: PaginationProviderProps) => {
   const getPrevItem = (
     items: SidebarItemType[],
     index: number
-  ): SidebarItemType | undefined => {
-    let foundItem: SidebarItemType | undefined
+  ): SidebarItemWithParent | undefined => {
+    let foundItem: SidebarItemWithParent | undefined
     items
       .slice(0, index)
       .reverse()
       .some((item) => {
         if (item.children?.length) {
-          foundItem = getPrevItem(item.children, item.children.length)
+          const childItem = getPrevItem(item.children, item.children.length)
+          if (childItem) {
+            foundItem = {
+              ...childItem,
+              parent: item,
+            }
+          }
         } else if (item.path) {
           foundItem = item
         }
@@ -87,13 +98,19 @@ export const PaginationProvider = ({ children }: PaginationProviderProps) => {
   const getNextItem = (
     items: SidebarItemType[],
     index: number
-  ): SidebarItemType | undefined => {
-    let foundItem: SidebarItemType | undefined
+  ): SidebarItemWithParent | undefined => {
+    let foundItem: SidebarItemWithParent | undefined
     items.slice(index + 1).some((item) => {
       if (item.path) {
         foundItem = item
       } else if (item.children?.length) {
-        foundItem = getNextItem(item.children, -1)
+        const childItem = getNextItem(item.children, -1)
+        if (childItem) {
+          foundItem = {
+            ...childItem,
+            parent: item,
+          }
+        }
       }
 
       return foundItem !== undefined
@@ -157,6 +174,7 @@ export const PaginationProvider = ({ children }: PaginationProviderProps) => {
           ? {
               title: result.prevItem.title,
               link: result.prevItem.path || "",
+              parentTitle: result.prevItem.parent?.title,
             }
           : undefined
       )
@@ -165,6 +183,7 @@ export const PaginationProvider = ({ children }: PaginationProviderProps) => {
           ? {
               title: result.nextItem.title,
               link: result.nextItem.path || "",
+              parentTitle: result.nextItem.parent?.title,
             }
           : undefined
       )

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

@@ -59,7 +59,7 @@ export type SidebarContextType = {
   setDesktopSidebarOpen: React.Dispatch<React.SetStateAction<boolean>>
   staticSidebarItems?: boolean
   shouldHandleHashChange: boolean
-  sidebarRef: React.RefObject<HTMLUListElement>
+  sidebarRef: React.RefObject<HTMLDivElement>
   goBack: () => void
 } & SidebarStyleOptions
 
@@ -198,7 +198,7 @@ export const SidebarProvider = ({
   const [activePath, setActivePath] = useState<string | null>("")
   const [mobileSidebarOpen, setMobileSidebarOpen] = useState<boolean>(false)
   const [desktopSidebarOpen, setDesktopSidebarOpen] = useState(true)
-  const sidebarRef = useRef<HTMLUListElement>(null)
+  const sidebarRef = useRef<HTMLDivElement>(null)
 
   const pathname = usePathname()
   const router = useRouter()
@@ -311,7 +311,7 @@ export const SidebarProvider = ({
     }
 
     setActivePath(backItem.path!)
-    setCurrentItems(currentItems.previousSidebar)
+    setCurrentItems(previousSidebar)
     router.replace(backItem.path!)
   }
 
@@ -405,7 +405,10 @@ export const SidebarProvider = ({
         bottom: [],
         mobile: items.mobile,
         parentItem: parentItem,
-        previousSidebar: currentItems,
+        previousSidebar:
+          currentItems?.previousSidebar?.parentItem?.path !== parentItem.path
+            ? currentItems
+            : undefined,
       })
     }
   }, [getCurrentSidebar, activePath])

www/packages/docs-ui/src/utils/get-navbar-items.ts

@@ -1,17 +1,29 @@
-import { NavbarLinkProps, navbarItems } from ".."
+import { NavbarItem, legacyNavbarItems, navbarItemsV1, navbarItemsV2 } from ".."
 
 type Options = {
   basePath: string
   activePath: string
+  version?: "v1" | "v2" | "legacy"
 }
 
 export function getNavbarItems({
   basePath,
   activePath,
-}: Options): NavbarLinkProps[] {
-  return navbarItems.map((item) => ({
-    ...item,
-    isActive: activePath === item.href,
-    href: `${basePath}${item.href}`,
-  }))
+  version = "legacy"
+}: Options): NavbarItem[] {
+  const navbarItems = version === "v2" ? navbarItemsV2 : version === "v1" ? navbarItemsV1 : legacyNavbarItems
+  return navbarItems.map((item) => {
+    if (item.type === "divider") {
+      return item
+    }
+
+    return {
+      ...item,
+      props: {
+        ...item.props,
+        isActive: activePath === item.props?.href,
+        href: `${basePath}${item.props?.href}`,
+      }
+    }
+  })
 }