docs: revise commerce modules overview pages (#10738)

* revise API Key Module overview

* revise auth module

* support ref sidebar items

* remove examples

* revise cart module

* revise currency

* revise customer module

* revise fulfillment module

* revise inventory module

* revise order module

* revise payment

* revise pricing module

* revise product module

* revise promotion module

* revise region module

* revise sales channel module

* revise stock location module

* revise store module

* revise tax module

* revise user module

* lint content + fix snippets

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

@@ -88,23 +88,35 @@ async function getAutogeneratedSidebarItems(
 }
 
 async function getAutogeneratedTagSidebarItems(
-  tags: string
+  tags: string,
+  type: "link" | "ref",
+  existingChildren?: RawSidebarItem[]
 ): Promise<ItemsToAdd[]> {
   const items: ItemsToAdd[] = []
 
   const parsedTags = parseTags(tags)
 
   items.push(
-    ...parsedTags.map(
-      (tagItem) =>
-        ({
-          type: "link",
-          ...tagItem,
-        }) as ItemsToAdd
-    )
+    ...parsedTags
+      .filter((tagItem) => {
+        return existingChildren?.every((existingItem) => {
+          if (existingItem.type !== "link" && existingItem.type !== "ref") {
+            return true
+          }
+
+          return existingItem.path !== tagItem.path
+        })
+      })
+      .map(
+        (tagItem) =>
+          ({
+            type,
+            ...tagItem,
+          }) as ItemsToAdd
+      )
   )
 
-  return sidebarAttachHrefCommonOptions(items)
+  return sidebarAttachHrefCommonOptions([...(existingChildren || []), ...items])
 }
 
 async function checkItem(item: RawSidebarItem): Promise<RawSidebarItem> {
@@ -130,7 +142,9 @@ async function checkItem(item: RawSidebarItem): Promise<RawSidebarItem> {
     })
   } else if (item.autogenerate_tags) {
     item.children = await getAutogeneratedTagSidebarItems(
-      item.autogenerate_tags
+      item.autogenerate_tags,
+      item.autogenerate_as_ref ? "ref" : "link",
+      item.children
     )
   } else if (
     item.custom_autogenerate &&
@@ -138,21 +152,29 @@ async function checkItem(item: RawSidebarItem): Promise<RawSidebarItem> {
   ) {
     item.children = await customGenerators[item.custom_autogenerate]()
   } else if (item.children) {
-    item.children = await Promise.all(
-      item.children.map(async (childItem) => await checkItem(childItem))
-    )
+    item.children = await checkItems(item.children)
   }
 
   return item
 }
 
+async function checkItems(items: RawSidebarItem[]): Promise<RawSidebarItem[]> {
+  return (
+    await Promise.all(items.map(async (item) => await checkItem(item)))
+  ).filter((item) => {
+    if (item.type !== "category" && item.type !== "sub-category") {
+      return true
+    }
+
+    return (item.children?.length || 0) > 0
+  })
+}
+
 export async function generateSidebar(sidebar: RawSidebarItem[]) {
   const path = await import("path")
   const { writeFileSync } = await import("fs")
 
-  const normalizedSidebar = await Promise.all(
-    sidebar.map(async (item) => await checkItem(item))
-  )
+  const normalizedSidebar = await checkItems(sidebar)
 
   const generatedDirPath = path.resolve("generated")
 

www/packages/build-scripts/src/utils/parse-tags.ts

@@ -27,14 +27,11 @@ const getIntersectionTags = (tags: string): Tag => {
     .map((tagName) => getTagItems(tagName))
     .filter((tag) => tag !== undefined) as Tag[]
 
-  if (!tagsToIntersect.length) {
+  if (tagsToIntersect.length < 2) {
+    // if there are less than 2 tags to intersect, return an empty array
     return []
   }
 
-  if (tagsToIntersect.length === 1) {
-    return tagsToIntersect[0]
-  }
-
   return tagsToIntersect[0].filter((tagItem) => {
     return tagsToIntersect
       .slice(1)

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

@@ -4,7 +4,12 @@ import React, { useMemo } from "react"
 import clsx from "clsx"
 import Link from "next/link"
 import { SidebarItemLink } from "types"
-import { CurrentItemsState, useSidebar, useSiteConfig } from "../../providers"
+import {
+  CurrentItemsState,
+  isSidebarItemLink,
+  useSidebar,
+  useSiteConfig,
+} from "../../providers"
 import { Button } from "../Button"
 import { TriangleRightMini } from "@medusajs/icons"
 
@@ -29,22 +34,20 @@ export const Breadcrumbs = () => {
       tempBreadcrumbItems = getBreadcrumbsOfItem(item.previousSidebar)
     }
 
-    const parentPath =
-      item.parentItem?.type === "link"
-        ? getLinkPath(item.parentItem)
-        : (item.parentItem?.type === "category" &&
-              breadcrumbOptions?.showCategories) ||
-            item.parentItem?.type === "sub-category"
-          ? "#"
-          : undefined
-    const firstItemPath =
-      item.default[0].type === "link"
-        ? getLinkPath(item.default[0])
-        : (item.default[0].type === "category" &&
-              breadcrumbOptions?.showCategories) ||
-            item.default[0].type === "sub-category"
-          ? "#"
-          : undefined
+    const parentPath = isSidebarItemLink(item.parentItem)
+      ? getLinkPath(item.parentItem)
+      : (item.parentItem?.type === "category" &&
+            breadcrumbOptions?.showCategories) ||
+          item.parentItem?.type === "sub-category"
+        ? "#"
+        : undefined
+    const firstItemPath = isSidebarItemLink(item.default[0])
+      ? getLinkPath(item.default[0])
+      : (item.default[0].type === "category" &&
+            breadcrumbOptions?.showCategories) ||
+          item.default[0].type === "sub-category"
+        ? "#"
+        : undefined
 
     const breadcrumbPath = parentPath || firstItemPath || "/"
 
@@ -76,7 +79,7 @@ export const Breadcrumbs = () => {
           breadcrumbOptions?.showCategories)
       ) {
         tempBreadcrumbItems.set(
-          sidebarActiveItem.parentItem.type === "link"
+          isSidebarItemLink(sidebarActiveItem.parentItem)
             ? getLinkPath(sidebarActiveItem.parentItem) || "#"
             : "#",
           sidebarActiveItem.parentItem.chapterTitle ||

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

@@ -1,193 +1,10 @@
 "use client"
 
-import React, { useMemo } from "react"
-import { Card, CardList, H2, useSidebar } from "../.."
-import { InteractiveSidebarItem, SidebarItem, SidebarItemLink } from "types"
-import slugify from "slugify"
-import { MDXComponents } from "../.."
+import React from "react"
+import { useChildDocs, UseChildDocsProps } from "../.."
 
-const Hr = MDXComponents["hr"] as () => React.JSX.Element
+export const ChildDocs = (props: UseChildDocsProps) => {
+  const { component } = useChildDocs(props)
 
-type ChildDocsProps = {
-  onlyTopLevel?: boolean
-  type?: "sidebar" | "item"
-  hideItems?: string[]
-  showItems?: string[]
-  hideTitle?: boolean
-  childLevel?: number
-}
-
-export const ChildDocs = ({
-  onlyTopLevel = false,
-  hideItems = [],
-  showItems,
-  type = "sidebar",
-  hideTitle = false,
-  childLevel = 1,
-}: ChildDocsProps) => {
-  const { currentItems, activeItem } = useSidebar()
-  const filterType = useMemo(() => {
-    return showItems !== undefined
-      ? "show"
-      : hideItems.length > 0
-        ? "hide"
-        : "all"
-  }, [showItems, hideItems])
-
-  const filterCondition = (item: SidebarItem): boolean => {
-    if (item.type === "separator") {
-      return false
-    }
-    switch (filterType) {
-      case "hide":
-        return (
-          (item.type !== "link" || !hideItems.includes(item.path)) &&
-          !hideItems.includes(item.title)
-        )
-      case "show":
-        return (
-          (item.type === "link" && showItems!.includes(item.path)) ||
-          showItems!.includes(item.title)
-        )
-      case "all":
-        return true
-    }
-  }
-
-  const filterItems = (items: SidebarItem[]): SidebarItem[] => {
-    return items
-      .filter(filterCondition)
-      .map((item) => Object.assign({}, item))
-      .map((item) => {
-        if (
-          item.type !== "separator" &&
-          item.children &&
-          filterType === "hide"
-        ) {
-          item.children = filterItems(item.children)
-        }
-
-        return item
-      })
-  }
-
-  const filteredItems = useMemo(() => {
-    const targetItems =
-      type === "sidebar"
-        ? currentItems
-          ? Object.assign({}, currentItems)
-          : undefined
-        : {
-            default: [...(activeItem?.children || [])],
-          }
-    if (filterType === "all" || !targetItems) {
-      return targetItems
-    }
-
-    return {
-      ...targetItems,
-      default: filterItems(targetItems.default),
-    }
-  }, [currentItems, type, activeItem, filterItems])
-
-  const filterNonInteractiveItems = (
-    items: SidebarItem[] | undefined
-  ): InteractiveSidebarItem[] => {
-    return (
-      (items?.filter(
-        (item) => item.type !== "separator"
-      ) as InteractiveSidebarItem[]) || []
-    )
-  }
-
-  const getChildrenForLevel = (
-    item: InteractiveSidebarItem,
-    currentLevel = 1
-  ): InteractiveSidebarItem[] | undefined => {
-    if (currentLevel === childLevel) {
-      return filterNonInteractiveItems(item.children)
-    }
-    if (!item.children) {
-      return
-    }
-
-    const childrenResult: InteractiveSidebarItem[] = []
-
-    filterNonInteractiveItems(item.children).forEach((child) => {
-      const childChildren = getChildrenForLevel(child, currentLevel + 1)
-
-      if (!childChildren) {
-        return
-      }
-
-      childrenResult.push(...childChildren)
-    })
-
-    return childrenResult
-  }
-
-  const getTopLevelElms = (items?: SidebarItem[]) => {
-    return (
-      <CardList
-        items={
-          filterNonInteractiveItems(items).map((childItem) => {
-            const href =
-              childItem.type === "link"
-                ? childItem.path
-                : childItem.children?.length
-                  ? (
-                      childItem.children.find(
-                        (item) => item.type === "link"
-                      ) as SidebarItemLink
-                    )?.path
-                  : "#"
-            return {
-              title: childItem.title,
-              href,
-            }
-          }) || []
-        }
-      />
-    )
-  }
-
-  const getAllLevelsElms = (items?: SidebarItem[]) => {
-    const filteredItems = filterNonInteractiveItems(items)
-    return filteredItems.map((item, key) => {
-      const itemChildren = getChildrenForLevel(item)
-      const HeadingComponent = itemChildren?.length ? H2 : undefined
-
-      return (
-        <React.Fragment key={key}>
-          {HeadingComponent && (
-            <>
-              {!hideTitle && (
-                <HeadingComponent id={slugify(item.title)}>
-                  {item.title}
-                </HeadingComponent>
-              )}
-              <CardList
-                items={
-                  itemChildren?.map((childItem) => ({
-                    title: childItem.title,
-                    href: childItem.type === "link" ? childItem.path : "",
-                  })) || []
-                }
-              />
-              {key !== filteredItems.length - 1 && <Hr />}
-            </>
-          )}
-          {!HeadingComponent && item.type === "link" && (
-            <Card title={item.title} href={item.path} />
-          )}
-        </React.Fragment>
-      )
-    })
-  }
-
-  const getElms = (items?: SidebarItem[]) => {
-    return onlyTopLevel ? getTopLevelElms(items) : getAllLevelsElms(items)
-  }
-
-  return <>{getElms(filteredItems?.default)}</>
+  return <>{component}</>
 }

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

@@ -120,3 +120,5 @@ export const MDXComponents: MDXComponentsType = {
     return <ZoomImg {...rest} />
   },
 }
+
+export const Hr = MDXComponents["hr"] as () => React.JSX.Element

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

@@ -30,6 +30,7 @@ export const SidebarItem = ({
     case "sub-category":
       return <SidebarItemSubCategory item={item} {...props} />
     case "link":
+    case "ref":
       return <SidebarItemLink item={item} {...props} />
     case "separator":
       return <DottedSeparator />

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

@@ -1,7 +1,7 @@
 "use client"
 
 import React, { Suspense, useMemo, useRef } from "react"
-import { useSidebar } from "@/providers"
+import { isSidebarItemLink, useSidebar } from "@/providers"
 import clsx from "clsx"
 import { Loading } from "@/components"
 import { SidebarItem } from "./Item"
@@ -139,7 +139,7 @@ export const Sidebar = ({
                     const itemKey =
                       item.type === "separator"
                         ? index
-                        : item.type === "link"
+                        : isSidebarItemLink(item)
                           ? `${item.path}-${index}`
                           : `${item.title}-${index}`
                     return (

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

@@ -1,4 +1,5 @@
 export * from "./use-active-on-scroll"
+export * from "./use-child-docs"
 export * from "./use-click-outside"
 export * from "./use-collapsible"
 export * from "./use-collapsible-code-lines"

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

@@ -0,0 +1,228 @@
+"use client"
+
+import React, { useMemo } from "react"
+import {
+  Card,
+  CardList,
+  H2,
+  H3,
+  H4,
+  Hr,
+  isSidebarItemLink,
+  useSidebar,
+} from "../.."
+import { InteractiveSidebarItem, SidebarItem, SidebarItemLink } from "types"
+import slugify from "slugify"
+import { MDXComponents } from "../.."
+
+type HeadingComponent = (
+  props: React.HTMLAttributes<HTMLHeadingElement>
+) => React.JSX.Element
+
+export type UseChildDocsProps = {
+  onlyTopLevel?: boolean
+  type?: "sidebar" | "item"
+  hideItems?: string[]
+  showItems?: string[]
+  hideTitle?: boolean
+  titleLevel?: number
+  childLevel?: number
+  itemsPerRow?: number
+}
+
+export const useChildDocs = ({
+  onlyTopLevel = false,
+  hideItems = [],
+  showItems,
+  type = "sidebar",
+  hideTitle = false,
+  titleLevel = 2,
+  childLevel = 1,
+  itemsPerRow,
+}: UseChildDocsProps) => {
+  const { currentItems, activeItem } = useSidebar()
+  const TitleHeaderComponent: HeadingComponent = useMemo(() => {
+    switch (titleLevel) {
+      case 3:
+        return H3
+      case 4:
+        return H4
+      case 5:
+        return MDXComponents["h5"] as HeadingComponent
+      case 6:
+        return MDXComponents["h6"] as HeadingComponent
+      default:
+        return H2
+    }
+  }, [titleLevel])
+  const filterType = useMemo(() => {
+    return showItems !== undefined
+      ? "show"
+      : hideItems.length > 0
+        ? "hide"
+        : "all"
+  }, [showItems, hideItems])
+
+  const filterCondition = (item: SidebarItem): boolean => {
+    if (item.type === "separator") {
+      return false
+    }
+    switch (filterType) {
+      case "hide":
+        return (
+          (!isSidebarItemLink(item) || !hideItems.includes(item.path)) &&
+          !hideItems.includes(item.title)
+        )
+      case "show":
+        return (
+          (isSidebarItemLink(item) && showItems!.includes(item.path)) ||
+          showItems!.includes(item.title)
+        )
+      case "all":
+        return true
+    }
+  }
+
+  const filterItems = (items: SidebarItem[]): SidebarItem[] => {
+    return items
+      .filter(filterCondition)
+      .map((item) => Object.assign({}, item))
+      .map((item) => {
+        if (
+          item.type !== "separator" &&
+          item.children &&
+          filterType === "hide"
+        ) {
+          item.children = filterItems(item.children)
+        }
+
+        return item
+      })
+  }
+
+  const filteredItems = useMemo(() => {
+    const targetItems =
+      type === "sidebar"
+        ? currentItems
+          ? Object.assign({}, currentItems)
+          : undefined
+        : {
+            default: [...(activeItem?.children || [])],
+          }
+    if (filterType === "all" || !targetItems) {
+      return targetItems
+    }
+
+    return {
+      ...targetItems,
+      default: filterItems(targetItems.default),
+    }
+  }, [currentItems, type, activeItem, filterItems])
+
+  const filterNonInteractiveItems = (
+    items: SidebarItem[] | undefined
+  ): InteractiveSidebarItem[] => {
+    return (
+      (items?.filter(
+        (item) => item.type !== "separator"
+      ) as InteractiveSidebarItem[]) || []
+    )
+  }
+
+  const getChildrenForLevel = (
+    item: InteractiveSidebarItem,
+    currentLevel = 1
+  ): InteractiveSidebarItem[] | undefined => {
+    if (currentLevel === childLevel) {
+      return filterNonInteractiveItems(item.children)
+    }
+    if (!item.children) {
+      return
+    }
+
+    const childrenResult: InteractiveSidebarItem[] = []
+
+    filterNonInteractiveItems(item.children).forEach((child) => {
+      const childChildren = getChildrenForLevel(child, currentLevel + 1)
+
+      if (!childChildren) {
+        return
+      }
+
+      childrenResult.push(...childChildren)
+    })
+
+    return childrenResult
+  }
+
+  const getTopLevelElms = (items?: SidebarItem[]) => {
+    return (
+      <CardList
+        items={
+          filterNonInteractiveItems(items).map((childItem) => {
+            const href = isSidebarItemLink(childItem)
+              ? childItem.path
+              : childItem.children?.length
+                ? (
+                    childItem.children.find((item) =>
+                      isSidebarItemLink(item)
+                    ) as SidebarItemLink
+                  )?.path
+                : "#"
+            return {
+              title: childItem.title,
+              href,
+            }
+          }) || []
+        }
+        itemsPerRow={itemsPerRow}
+      />
+    )
+  }
+
+  const getAllLevelsElms = (items?: SidebarItem[]) => {
+    const filteredItems = filterNonInteractiveItems(items)
+    return filteredItems.map((item, key) => {
+      const itemChildren = getChildrenForLevel(item)
+      const HeadingComponent = itemChildren?.length
+        ? TitleHeaderComponent
+        : undefined
+
+      return (
+        <React.Fragment key={key}>
+          {HeadingComponent && (
+            <>
+              {!hideTitle && (
+                <HeadingComponent id={slugify(item.title.toLowerCase())}>
+                  {item.title}
+                </HeadingComponent>
+              )}
+              <CardList
+                items={
+                  itemChildren?.map((childItem) => ({
+                    title: childItem.title,
+                    href: isSidebarItemLink(childItem) ? childItem.path : "",
+                  })) || []
+                }
+                itemsPerRow={itemsPerRow}
+              />
+              {key !== filteredItems.length - 1 && <Hr />}
+            </>
+          )}
+          {!HeadingComponent && isSidebarItemLink(item) && (
+            <Card title={item.title} href={item.path} />
+          )}
+        </React.Fragment>
+      )
+    })
+  }
+
+  const getElms = (items?: SidebarItem[]) => {
+    return onlyTopLevel ? getTopLevelElms(items) : getAllLevelsElms(items)
+  }
+
+  return {
+    items: filteredItems,
+    component: getElms(filteredItems?.default),
+  }
+}

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

@@ -7,7 +7,7 @@ import React, {
   useMemo,
   useState,
 } from "react"
-import { useSidebar } from "../Sidebar"
+import { isSidebarItemLink, useSidebar } from "../Sidebar"
 import { usePrevious } from "@uidotdev/usehooks"
 import { InteractiveSidebarItem, SidebarItem } from "types"
 
@@ -56,7 +56,7 @@ export const PaginationProvider = ({ children }: PaginationProviderProps) => {
       return undefined
     }
 
-    return children[0].type === "link"
+    return isSidebarItemLink(children[0])
       ? {
           ...children[0],
           parent: item,
@@ -69,7 +69,7 @@ export const PaginationProvider = ({ children }: PaginationProviderProps) => {
   ): SidebarItemWithParent[] | undefined => {
     return item.children?.filter(
       (childItem) =>
-        childItem.type === "link" ||
+        isSidebarItemLink(childItem) ||
         (childItem.type !== "separator" &&
           getChildrenWithPages(childItem)?.length)
     ) as SidebarItemWithParent[]
@@ -95,7 +95,7 @@ export const PaginationProvider = ({ children }: PaginationProviderProps) => {
               parent: item,
             }
           }
-        } else if (item.type === "link") {
+        } else if (isSidebarItemLink(item)) {
           foundItem = item
         }
 
@@ -115,7 +115,7 @@ export const PaginationProvider = ({ children }: PaginationProviderProps) => {
         return false
       }
 
-      if (item.type === "link") {
+      if (isSidebarItemLink(item)) {
         foundItem = item
       } else if (item.children?.length) {
         const childItem = getNextItem(item.children, -1)
@@ -139,7 +139,7 @@ export const PaginationProvider = ({ children }: PaginationProviderProps) => {
     }
 
     result.foundActive = currentItems.some((item, index) => {
-      if (item.type === "link" && item.path === activePath) {
+      if (isSidebarItemLink(item) && item.path === activePath) {
         if (index !== 0) {
           result.prevItem = getPrevItem(currentItems, index)
         }
@@ -161,8 +161,9 @@ export const PaginationProvider = ({ children }: PaginationProviderProps) => {
           result.prevItem = childrenResult.prevItem
           result.nextItem = childrenResult.nextItem
           if (!result.prevItem) {
-            result.prevItem =
-              item.type === "link" ? item : getPrevItem(currentItems, index)
+            result.prevItem = isSidebarItemLink(item)
+              ? item
+              : getPrevItem(currentItems, index)
           }
 
           if (!result.nextItem && index !== currentItems.length - 1) {
@@ -186,7 +187,9 @@ export const PaginationProvider = ({ children }: PaginationProviderProps) => {
         result.prevItem
           ? {
               title: result.prevItem.title,
-              link: result.prevItem.type === "link" ? result.prevItem.path : "",
+              link: isSidebarItemLink(result.prevItem)
+                ? result.prevItem.path
+                : "",
               parentTitle:
                 result.prevItem.parent?.type !== "separator"
                   ? result.prevItem.parent?.title
@@ -198,7 +201,9 @@ export const PaginationProvider = ({ children }: PaginationProviderProps) => {
         result.nextItem
           ? {
               title: result.nextItem.title,
-              link: result.nextItem.type === "link" ? result.nextItem.path : "",
+              link: isSidebarItemLink(result.nextItem)
+                ? result.nextItem.path
+                : "",
               parentTitle:
                 result.nextItem.parent?.type !== "separator"
                   ? result.nextItem.parent?.title

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

@@ -95,13 +95,26 @@ export type ActionType =
 
 type LinksMap = Map<string, SidebarItemLinkWithParent>
 
+export const isSidebarItemLink = (
+  item: SidebarItem | undefined,
+  checkRef = true
+): item is SidebarItemLink => {
+  return (
+    item !== undefined &&
+    (item.type === "link" || (checkRef && item.type === "ref"))
+  )
+}
+
 const areItemsEqual = (itemA: SidebarItem, itemB: SidebarItem): boolean => {
   if (itemA.type === "separator" || itemB.type === "separator") {
     return false
   }
   const hasSameTitle = itemA.title === itemB.title
   const hasSamePath =
-    itemA.type === "link" && itemB.type === "link" && itemA.path === itemB.path
+    isSidebarItemLink(itemA) &&
+    isSidebarItemLink(itemB) &&
+    itemA.type === itemB.type &&
+    itemA.path === itemB.path
 
   return hasSameTitle || hasSamePath
 }
@@ -116,8 +129,8 @@ const findItem = (
     if (i.type === "separator") {
       return false
     }
-    if (areItemsEqual(item as SidebarItem, i) && i.type === "link") {
-      foundItem = i
+    if (areItemsEqual(item as SidebarItem, i)) {
+      foundItem = i as SidebarItemLink
     } else if (checkChildren && i.children) {
       foundItem = findItem(i.children, item)
       if (foundItem && !foundItem.parentItem) {
@@ -143,7 +156,7 @@ const getLinksMap = (
       return
     }
 
-    if (item.type === "link") {
+    if (isSidebarItemLink(item)) {
       map.set(item.path, {
         ...item,
         parentItem,
@@ -246,7 +259,7 @@ export const reducer = (
                   : [...(i.children || []), ...items],
               loaded: parent.changeLoaded
                 ? true
-                : i.type === "link"
+                : isSidebarItemLink(i)
                   ? i.loaded
                   : true,
             }
@@ -355,8 +368,8 @@ export const SidebarProvider = ({
   }
 
   const isLinkActive = useCallback(
-    (item: SidebarItem, checkChildren = false): boolean => {
-      if (item.type !== "link") {
+    (item: SidebarItem, checkChildren = false, checkRef = true): boolean => {
+      if (!isSidebarItemLink(item, checkRef)) {
         return false
       }
 
@@ -399,24 +412,28 @@ export const SidebarProvider = ({
         if (item.type === "separator") {
           return false
         }
-        if (item.isChildSidebar && isLinkActive(item)) {
+        if (item.isChildSidebar && isLinkActive(item, false, false)) {
           currentSidebar = item
+          return true
+        }
+        if (!item.children?.length) {
+          return false
         }
 
-        if (!currentSidebar && item.children?.length) {
-          const childSidebar =
-            getCurrentSidebar(item.children) ||
-            (activePath
-              ? findItem(item.children, {
-                  path: activePath || undefined,
-                  type: "link",
-                })
-              : undefined)
+        const childSidebar =
+          getCurrentSidebar(item.children) ||
+          (activePath
+            ? findItem(item.children, {
+                path: activePath,
+                type: "link",
+              })
+            : undefined)
 
-          if (childSidebar) {
-            currentSidebar = childSidebar.isChildSidebar ? childSidebar : item
-          }
-        }
+        currentSidebar = childSidebar
+          ? childSidebar.isChildSidebar
+            ? childSidebar
+            : item
+          : undefined
 
         return currentSidebar !== undefined
       })
@@ -434,7 +451,7 @@ export const SidebarProvider = ({
     const previousSidebar = currentItems.previousSidebar || items
 
     const backItem = previousSidebar.default.find(
-      (item) => item.type === "link" && !item.isChildSidebar
+      (item) => isSidebarItemLink(item) && !item.isChildSidebar
     ) as SidebarItemLink
 
     if (!backItem) {
@@ -472,7 +489,7 @@ export const SidebarProvider = ({
     const handleScroll = () => {
       if (getScrolledTop(resolvedScrollableElement) === 0) {
         const firstItemPath =
-          items.default.length && items.default[0].type === "link"
+          items.default.length && isSidebarItemLink(items.default[0])
             ? items.default[0].path
             : ""
         setActivePath(firstItemPath)
@@ -548,8 +565,8 @@ export const SidebarProvider = ({
     ) {
       const { children, ...parentItem } = currentSidebar
       const hasPreviousSidebar =
-        currentItems?.previousSidebar?.parentItem?.type === "link" &&
-        parentItem.type === "link" &&
+        isSidebarItemLink(currentItems?.previousSidebar?.parentItem) &&
+        isSidebarItemLink(parentItem) &&
         currentItems.previousSidebar.parentItem.path !== parentItem.path
 
       setCurrentItems({

www/packages/tags/src/tags/api-key.ts

@@ -1,7 +1,7 @@
 export const apiKey = [
   {
     "title": "Use a Publishable API Key in the Storefront",
-    "path": "/app/storefront-development/publishable-api-keys"
+    "path": "/storefront-development/publishable-api-keys"
   },
   {
     "title": "createApiKeysStep",

www/packages/tags/src/tags/auth.ts

@@ -1,27 +1,27 @@
 export const auth = [
   {
     "title": "Log-out Customer in Storefront",
-    "path": "/app/storefront-development/customers/log-out"
+    "path": "/storefront-development/customers/log-out"
   },
   {
     "title": "Login Customer in Storefront",
-    "path": "/app/storefront-development/customers/login"
+    "path": "/storefront-development/customers/login"
   },
   {
     "title": "Register Customer in Storefront",
-    "path": "/app/storefront-development/customers/register"
+    "path": "/storefront-development/customers/register"
   },
   {
     "title": "Reset Customer Password in Storefront",
-    "path": "/app/storefront-development/customers/reset-password"
+    "path": "/storefront-development/customers/reset-password"
   },
   {
     "title": "Retrieve Customer in Storefront",
-    "path": "/app/storefront-development/customers/retrieve"
+    "path": "/storefront-development/customers/retrieve"
   },
   {
     "title": "Third-Party or Social Login in Storefront",
-    "path": "/app/storefront-development/customers/third-party-login"
+    "path": "/storefront-development/customers/third-party-login"
   },
   {
     "title": "setAuthAppMetadataStep",

www/packages/tags/src/tags/cart.ts

@@ -1,47 +1,47 @@
 export const cart = [
   {
     "title": "Create Cart Context in Storefront",
-    "path": "/app/storefront-development/cart/context"
+    "path": "/storefront-development/cart/context"
   },
   {
     "title": "Create Cart in Storefront",
-    "path": "/app/storefront-development/cart/create"
+    "path": "/storefront-development/cart/create"
   },
   {
     "title": "Manage Cart's Items in Storefront",
-    "path": "/app/storefront-development/cart/manage-items"
+    "path": "/storefront-development/cart/manage-items"
   },
   {
     "title": "Retrieve Cart in Storefront",
-    "path": "/app/storefront-development/cart/retrieve"
+    "path": "/storefront-development/cart/retrieve"
   },
   {
     "title": "Update Cart in Storefront",
-    "path": "/app/storefront-development/cart/update"
+    "path": "/storefront-development/cart/update"
   },
   {
     "title": "Checkout Step 2: Enter Address",
-    "path": "/app/storefront-development/checkout/address"
+    "path": "/storefront-development/checkout/address"
   },
   {
     "title": "Checkout Step 5: Complete Cart",
-    "path": "/app/storefront-development/checkout/complete-cart"
+    "path": "/storefront-development/checkout/complete-cart"
   },
   {
     "title": "Checkout Step 1: Enter Email",
-    "path": "/app/storefront-development/checkout/email"
+    "path": "/storefront-development/checkout/email"
   },
   {
     "title": "Checkout Step 4: Choose Payment Provider",
-    "path": "/app/storefront-development/checkout/payment"
+    "path": "/storefront-development/checkout/payment"
   },
   {
     "title": "Payment with Stripe in React Storefront",
-    "path": "/app/storefront-development/checkout/payment/stripe"
+    "path": "/storefront-development/checkout/payment/stripe"
   },
   {
     "title": "Checkout Step 3: Choose Shipping Method",
-    "path": "/app/storefront-development/checkout/shipping"
+    "path": "/storefront-development/checkout/shipping"
   },
   {
     "title": "addShippingMethodToCartStep",

www/packages/tags/src/tags/customer.ts

@@ -1,39 +1,39 @@
 export const customer = [
   {
     "title": "Manage Customer Addresses in Storefront",
-    "path": "/app/storefront-development/customers/addresses"
+    "path": "/storefront-development/customers/addresses"
   },
   {
     "title": "Customer Context in Storefront",
-    "path": "/app/storefront-development/customers/context"
+    "path": "/storefront-development/customers/context"
   },
   {
     "title": "Log-out Customer in Storefront",
-    "path": "/app/storefront-development/customers/log-out"
+    "path": "/storefront-development/customers/log-out"
   },
   {
     "title": "Login Customer in Storefront",
-    "path": "/app/storefront-development/customers/login"
+    "path": "/storefront-development/customers/login"
   },
   {
     "title": "Edit Customer Profile in Storefront",
-    "path": "/app/storefront-development/customers/profile"
+    "path": "/storefront-development/customers/profile"
   },
   {
     "title": "Register Customer in Storefront",
-    "path": "/app/storefront-development/customers/register"
+    "path": "/storefront-development/customers/register"
   },
   {
     "title": "Reset Customer Password in Storefront",
-    "path": "/app/storefront-development/customers/reset-password"
+    "path": "/storefront-development/customers/reset-password"
   },
   {
     "title": "Retrieve Customer in Storefront",
-    "path": "/app/storefront-development/customers/retrieve"
+    "path": "/storefront-development/customers/retrieve"
   },
   {
     "title": "Third-Party or Social Login in Storefront",
-    "path": "/app/storefront-development/customers/third-party-login"
+    "path": "/storefront-development/customers/third-party-login"
   },
   {
     "title": "findOrCreateCustomerStep",

www/packages/tags/src/tags/fulfillment.ts

@@ -1,7 +1,7 @@
 export const fulfillment = [
   {
     "title": "Checkout Step 3: Choose Shipping Method",
-    "path": "/app/storefront-development/checkout/shipping"
+    "path": "/storefront-development/checkout/shipping"
   },
   {
     "title": "validateCartShippingOptionsStep",

www/packages/tags/src/tags/index.ts

@@ -1,31 +1,32 @@
 export * from "./product.js"
-export * from "./tax.js"
+export * from "./server.js"
 export * from "./storefront.js"
-export * from "./order.js"
 export * from "./payment.js"
+export * from "./cart.js"
+export * from "./order.js"
 export * from "./stripe.js"
 export * from "./fulfillment.js"
 export * from "./customer.js"
-export * from "./auth.js"
-export * from "./pricing.js"
-export * from "./product-collection.js"
+export * from "./tax.js"
 export * from "./inventory.js"
-export * from "./publishable-api-key.js"
-export * from "./region.js"
+export * from "./pricing.js"
 export * from "./api-key.js"
-export * from "./step.js"
+export * from "./query.js"
+export * from "./publishable-api-key.js"
+export * from "./auth.js"
+export * from "./region.js"
+export * from "./product-collection.js"
 export * from "./remote-link.js"
-export * from "./sales-channel.js"
 export * from "./workflow.js"
-export * from "./remote-query.js"
+export * from "./sales-channel.js"
+export * from "./product-category.js"
+export * from "./step.js"
+export * from "./promotion.js"
 export * from "./event-bus.js"
 export * from "./store.js"
-export * from "./logger.js"
-export * from "./promotion.js"
-export * from "./locking.js"
 export * from "./file.js"
-export * from "./user.js"
-export * from "./product-category.js"
 export * from "./stock-location.js"
-export * from "./cart.js"
-export * from "./query.js"
+export * from "./locking.js"
+export * from "./user.js"
+export * from "./remote-query.js"
+export * from "./logger.js"

www/packages/tags/src/tags/inventory.ts

@@ -1,7 +1,7 @@
 export const inventory = [
   {
     "title": "Retrieve Product Variant's Inventory in Storefront",
-    "path": "/app/storefront-development/products/inventory"
+    "path": "/storefront-development/products/inventory"
   },
   {
     "title": "confirmInventoryStep",

www/packages/tags/src/tags/order.ts

@@ -1,7 +1,7 @@
 export const order = [
   {
     "title": "Checkout Step 5: Complete Cart",
-    "path": "/app/storefront-development/checkout/complete-cart"
+    "path": "/storefront-development/checkout/complete-cart"
   },
   {
     "title": "addOrderTransactionStep",

www/packages/tags/src/tags/payment.ts

@@ -1,15 +1,19 @@
 export const payment = [
+  {
+    "title": "Customize the Stripe Integration in the Next.js Starter",
+    "path": "/nextjs-starter/guides/customize-stripe"
+  },
   {
     "title": "Checkout Step 5: Complete Cart",
-    "path": "/app/storefront-development/checkout/complete-cart"
+    "path": "/storefront-development/checkout/complete-cart"
   },
   {
     "title": "Checkout Step 4: Choose Payment Provider",
-    "path": "/app/storefront-development/checkout/payment"
+    "path": "/storefront-development/checkout/payment"
   },
   {
     "title": "Payment with Stripe in React Storefront",
-    "path": "/app/storefront-development/checkout/payment/stripe"
+    "path": "/storefront-development/checkout/payment/stripe"
   },
   {
     "title": "createPaymentCollectionsStep",

www/packages/tags/src/tags/pricing.ts

@@ -1,27 +1,27 @@
 export const pricing = [
   {
     "title": "Get Variant Prices",
-    "path": "/app/commerce-modules/product/guides/price"
+    "path": "/commerce-modules/product/guides/price"
   },
   {
     "title": "Get Variant Price with Taxes",
-    "path": "/app/commerce-modules/product/guides/price-with-taxes"
+    "path": "/commerce-modules/product/guides/price-with-taxes"
   },
   {
     "title": "Example: Show Sale Price",
-    "path": "/app/storefront-development/products/price/examples/sale-price"
+    "path": "/storefront-development/products/price/examples/sale-price"
   },
   {
     "title": "Example: Show Variant's Price",
-    "path": "/app/storefront-development/products/price/examples/show-price"
+    "path": "/storefront-development/products/price/examples/show-price"
   },
   {
     "title": "Example: Show Price with Taxes",
-    "path": "/app/storefront-development/products/price/examples/tax-price"
+    "path": "/storefront-development/products/price/examples/tax-price"
   },
   {
     "title": "Retrieve Product Variant's Prices in Storefront",
-    "path": "/app/storefront-development/products/price"
+    "path": "/storefront-development/products/price"
   },
   {
     "title": "createShippingOptionsPriceSetsStep",

www/packages/tags/src/tags/product-category.ts

@@ -1,18 +1,18 @@
 export const productCategory = [
   {
     "title": "List Product Categories in Storefront",
-    "path": "/app/storefront-development/products/categories/list"
+    "path": "/storefront-development/products/categories/list"
   },
   {
     "title": "Retrieve Nested Categories in Storefront",
-    "path": "/app/storefront-development/products/categories/nested-categories"
+    "path": "/storefront-development/products/categories/nested-categories"
   },
   {
     "title": "Retrieve a Category's Products in Storefront",
-    "path": "/app/storefront-development/products/categories/products"
+    "path": "/storefront-development/products/categories/products"
   },
   {
     "title": "Retrieve a Category in Storefront",
-    "path": "/app/storefront-development/products/categories/retrieve"
+    "path": "/storefront-development/products/categories/retrieve"
   }
 ]

www/packages/tags/src/tags/product-collection.ts

@@ -1,14 +1,14 @@
 export const productCollection = [
   {
     "title": "List Product Collections in Storefront",
-    "path": "/app/storefront-development/products/collections/list"
+    "path": "/storefront-development/products/collections/list"
   },
   {
     "title": "Retrieve a Collection's Products in Storefront",
-    "path": "/app/storefront-development/products/collections/products"
+    "path": "/storefront-development/products/collections/products"
   },
   {
     "title": "Retrieve a Collection in Storefront",
-    "path": "/app/storefront-development/products/collections/retrieve"
+    "path": "/storefront-development/products/collections/retrieve"
   }
 ]

www/packages/tags/src/tags/product.ts

@@ -1,71 +1,71 @@
 export const product = [
   {
     "title": "Get Variant Prices",
-    "path": "/app/commerce-modules/product/guides/price"
+    "path": "/commerce-modules/product/guides/price"
   },
   {
     "title": "Get Variant Price with Taxes",
-    "path": "/app/commerce-modules/product/guides/price-with-taxes"
+    "path": "/commerce-modules/product/guides/price-with-taxes"
   },
   {
     "title": "List Product Categories in Storefront",
-    "path": "/app/storefront-development/products/categories/list"
+    "path": "/storefront-development/products/categories/list"
   },
   {
     "title": "Retrieve Nested Categories in Storefront",
-    "path": "/app/storefront-development/products/categories/nested-categories"
+    "path": "/storefront-development/products/categories/nested-categories"
   },
   {
     "title": "Retrieve a Category's Products in Storefront",
-    "path": "/app/storefront-development/products/categories/products"
+    "path": "/storefront-development/products/categories/products"
   },
   {
     "title": "Retrieve a Category in Storefront",
-    "path": "/app/storefront-development/products/categories/retrieve"
+    "path": "/storefront-development/products/categories/retrieve"
   },
   {
     "title": "List Product Collections in Storefront",
-    "path": "/app/storefront-development/products/collections/list"
+    "path": "/storefront-development/products/collections/list"
   },
   {
     "title": "Retrieve a Collection's Products in Storefront",
-    "path": "/app/storefront-development/products/collections/products"
+    "path": "/storefront-development/products/collections/products"
   },
   {
     "title": "Retrieve a Collection in Storefront",
-    "path": "/app/storefront-development/products/collections/retrieve"
+    "path": "/storefront-development/products/collections/retrieve"
   },
   {
     "title": "Retrieve Product Variant's Inventory in Storefront",
-    "path": "/app/storefront-development/products/inventory"
+    "path": "/storefront-development/products/inventory"
   },
   {
     "title": "List Products in Storefront",
-    "path": "/app/storefront-development/products/list"
+    "path": "/storefront-development/products/list"
   },
   {
     "title": "Example: Show Sale Price",
-    "path": "/app/storefront-development/products/price/examples/sale-price"
+    "path": "/storefront-development/products/price/examples/sale-price"
   },
   {
     "title": "Example: Show Variant's Price",
-    "path": "/app/storefront-development/products/price/examples/show-price"
+    "path": "/storefront-development/products/price/examples/show-price"
   },
   {
     "title": "Example: Show Price with Taxes",
-    "path": "/app/storefront-development/products/price/examples/tax-price"
+    "path": "/storefront-development/products/price/examples/tax-price"
   },
   {
     "title": "Retrieve Product Variant's Prices in Storefront",
-    "path": "/app/storefront-development/products/price"
+    "path": "/storefront-development/products/price"
   },
   {
     "title": "Retrieve a Product in Storefront",
-    "path": "/app/storefront-development/products/retrieve"
+    "path": "/storefront-development/products/retrieve"
   },
   {
     "title": "Select Product Variants in Storefront",
-    "path": "/app/storefront-development/products/variants"
+    "path": "/storefront-development/products/variants"
   },
   {
     "title": "batchLinkProductsToCollectionStep",

www/packages/tags/src/tags/publishable-api-key.ts

@@ -1,6 +1,6 @@
 export const publishableApiKey = [
   {
     "title": "Use a Publishable API Key in the Storefront",
-    "path": "/app/storefront-development/publishable-api-keys"
+    "path": "/storefront-development/publishable-api-keys"
   }
 ]

www/packages/tags/src/tags/query.ts

@@ -1,11 +1,11 @@
 export const query = [
   {
     "title": "Get Variant Prices",
-    "path": "/app/commerce-modules/product/guides/price"
+    "path": "/commerce-modules/product/guides/price"
   },
   {
     "title": "Get Variant Price with Taxes",
-    "path": "/app/commerce-modules/product/guides/price-with-taxes"
+    "path": "/commerce-modules/product/guides/price-with-taxes"
   },
   {
     "title": "addShippingMethodToCartWorkflow",

www/packages/tags/src/tags/region.ts

@@ -1,15 +1,15 @@
 export const region = [
   {
     "title": "Region Context in Storefront",
-    "path": "/app/storefront-development/regions/context"
+    "path": "/storefront-development/regions/context"
   },
   {
     "title": "List Regions in Storefront",
-    "path": "/app/storefront-development/regions/list"
+    "path": "/storefront-development/regions/list"
   },
   {
     "title": "Store and Retrieve Region",
-    "path": "/app/storefront-development/regions/store-retrieve-region"
+    "path": "/storefront-development/regions/store-retrieve-region"
   },
   {
     "title": "findOneOrAnyRegionStep",

www/packages/tags/src/tags/sales-channel.ts

@@ -1,4 +1,8 @@
 export const salesChannel = [
+  {
+    "title": "Use a Publishable API Key in the Storefront",
+    "path": "/storefront-development/publishable-api-keys"
+  },
   {
     "title": "validateSalesChannelsExistStep",
     "path": "/references/medusa-workflows/steps/validateSalesChannelsExistStep"

www/packages/tags/src/tags/server.ts

@@ -0,0 +1,10 @@
+export const server = [
+  {
+    "title": "Get Variant Prices",
+    "path": "/commerce-modules/product/guides/price"
+  },
+  {
+    "title": "Get Variant Price with Taxes",
+    "path": "/commerce-modules/product/guides/price-with-taxes"
+  }
+]

www/packages/tags/src/tags/storefront.ts

@@ -1,162 +1,166 @@
 export const storefront = [
+  {
+    "title": "Customize the Stripe Integration in the Next.js Starter",
+    "path": "/nextjs-starter/guides/customize-stripe"
+  },
   {
     "title": "Create Cart Context in Storefront",
-    "path": "/app/storefront-development/cart/context"
+    "path": "/storefront-development/cart/context"
   },
   {
     "title": "Create Cart in Storefront",
-    "path": "/app/storefront-development/cart/create"
+    "path": "/storefront-development/cart/create"
   },
   {
     "title": "Manage Cart's Items in Storefront",
-    "path": "/app/storefront-development/cart/manage-items"
+    "path": "/storefront-development/cart/manage-items"
   },
   {
     "title": "Retrieve Cart in Storefront",
-    "path": "/app/storefront-development/cart/retrieve"
+    "path": "/storefront-development/cart/retrieve"
   },
   {
     "title": "Update Cart in Storefront",
-    "path": "/app/storefront-development/cart/update"
+    "path": "/storefront-development/cart/update"
   },
   {
     "title": "Checkout Step 2: Enter Address",
-    "path": "/app/storefront-development/checkout/address"
+    "path": "/storefront-development/checkout/address"
   },
   {
     "title": "Checkout Step 5: Complete Cart",
-    "path": "/app/storefront-development/checkout/complete-cart"
+    "path": "/storefront-development/checkout/complete-cart"
   },
   {
     "title": "Checkout Step 1: Enter Email",
-    "path": "/app/storefront-development/checkout/email"
+    "path": "/storefront-development/checkout/email"
   },
   {
     "title": "Checkout Step 4: Choose Payment Provider",
-    "path": "/app/storefront-development/checkout/payment"
+    "path": "/storefront-development/checkout/payment"
   },
   {
     "title": "Payment with Stripe in React Storefront",
-    "path": "/app/storefront-development/checkout/payment/stripe"
+    "path": "/storefront-development/checkout/payment/stripe"
   },
   {
     "title": "Checkout Step 3: Choose Shipping Method",
-    "path": "/app/storefront-development/checkout/shipping"
+    "path": "/storefront-development/checkout/shipping"
   },
   {
     "title": "Manage Customer Addresses in Storefront",
-    "path": "/app/storefront-development/customers/addresses"
+    "path": "/storefront-development/customers/addresses"
   },
   {
     "title": "Customer Context in Storefront",
-    "path": "/app/storefront-development/customers/context"
+    "path": "/storefront-development/customers/context"
   },
   {
     "title": "Log-out Customer in Storefront",
-    "path": "/app/storefront-development/customers/log-out"
+    "path": "/storefront-development/customers/log-out"
   },
   {
     "title": "Login Customer in Storefront",
-    "path": "/app/storefront-development/customers/login"
+    "path": "/storefront-development/customers/login"
   },
   {
     "title": "Edit Customer Profile in Storefront",
-    "path": "/app/storefront-development/customers/profile"
+    "path": "/storefront-development/customers/profile"
   },
   {
     "title": "Register Customer in Storefront",
-    "path": "/app/storefront-development/customers/register"
+    "path": "/storefront-development/customers/register"
   },
   {
     "title": "Reset Customer Password in Storefront",
-    "path": "/app/storefront-development/customers/reset-password"
+    "path": "/storefront-development/customers/reset-password"
   },
   {
     "title": "Retrieve Customer in Storefront",
-    "path": "/app/storefront-development/customers/retrieve"
+    "path": "/storefront-development/customers/retrieve"
   },
   {
     "title": "Third-Party or Social Login in Storefront",
-    "path": "/app/storefront-development/customers/third-party-login"
+    "path": "/storefront-development/customers/third-party-login"
   },
   {
     "title": "List Product Categories in Storefront",
-    "path": "/app/storefront-development/products/categories/list"
+    "path": "/storefront-development/products/categories/list"
   },
   {
     "title": "Retrieve Nested Categories in Storefront",
-    "path": "/app/storefront-development/products/categories/nested-categories"
+    "path": "/storefront-development/products/categories/nested-categories"
   },
   {
     "title": "Retrieve a Category's Products in Storefront",
-    "path": "/app/storefront-development/products/categories/products"
+    "path": "/storefront-development/products/categories/products"
   },
   {
     "title": "Retrieve a Category in Storefront",
-    "path": "/app/storefront-development/products/categories/retrieve"
+    "path": "/storefront-development/products/categories/retrieve"
   },
   {
     "title": "List Product Collections in Storefront",
-    "path": "/app/storefront-development/products/collections/list"
+    "path": "/storefront-development/products/collections/list"
   },
   {
     "title": "Retrieve a Collection's Products in Storefront",
-    "path": "/app/storefront-development/products/collections/products"
+    "path": "/storefront-development/products/collections/products"
   },
   {
     "title": "Retrieve a Collection in Storefront",
-    "path": "/app/storefront-development/products/collections/retrieve"
+    "path": "/storefront-development/products/collections/retrieve"
   },
   {
     "title": "Retrieve Product Variant's Inventory in Storefront",
-    "path": "/app/storefront-development/products/inventory"
+    "path": "/storefront-development/products/inventory"
   },
   {
     "title": "List Products in Storefront",
-    "path": "/app/storefront-development/products/list"
+    "path": "/storefront-development/products/list"
   },
   {
     "title": "Example: Show Sale Price",
-    "path": "/app/storefront-development/products/price/examples/sale-price"
+    "path": "/storefront-development/products/price/examples/sale-price"
   },
   {
     "title": "Example: Show Variant's Price",
-    "path": "/app/storefront-development/products/price/examples/show-price"
+    "path": "/storefront-development/products/price/examples/show-price"
   },
   {
     "title": "Example: Show Price with Taxes",
-    "path": "/app/storefront-development/products/price/examples/tax-price"
+    "path": "/storefront-development/products/price/examples/tax-price"
   },
   {
     "title": "Retrieve Product Variant's Prices in Storefront",
-    "path": "/app/storefront-development/products/price"
+    "path": "/storefront-development/products/price"
   },
   {
     "title": "Retrieve a Product in Storefront",
-    "path": "/app/storefront-development/products/retrieve"
+    "path": "/storefront-development/products/retrieve"
   },
   {
     "title": "Select Product Variants in Storefront",
-    "path": "/app/storefront-development/products/variants"
+    "path": "/storefront-development/products/variants"
   },
   {
     "title": "Use a Publishable API Key in the Storefront",
-    "path": "/app/storefront-development/publishable-api-keys"
+    "path": "/storefront-development/publishable-api-keys"
   },
   {
     "title": "Region Context in Storefront",
-    "path": "/app/storefront-development/regions/context"
+    "path": "/storefront-development/regions/context"
   },
   {
     "title": "List Regions in Storefront",
-    "path": "/app/storefront-development/regions/list"
+    "path": "/storefront-development/regions/list"
   },
   {
     "title": "Store and Retrieve Region",
-    "path": "/app/storefront-development/regions/store-retrieve-region"
+    "path": "/storefront-development/regions/store-retrieve-region"
   },
   {
     "title": "Storefront Development Tips",
-    "path": "/app/storefront-development/tips"
+    "path": "/storefront-development/tips"
   }
 ]

www/packages/tags/src/tags/stripe.ts

@@ -1,6 +1,6 @@
 export const stripe = [
   {
     "title": "Payment with Stripe in React Storefront",
-    "path": "/app/storefront-development/checkout/payment/stripe"
+    "path": "/storefront-development/checkout/payment/stripe"
   }
 ]

www/packages/tags/src/tags/tax.ts

@@ -1,11 +1,11 @@
 export const tax = [
   {
     "title": "Get Variant Price with Taxes",
-    "path": "/app/commerce-modules/product/guides/price-with-taxes"
+    "path": "/commerce-modules/product/guides/price-with-taxes"
   },
   {
     "title": "Example: Show Price with Taxes",
-    "path": "/app/storefront-development/products/price/examples/tax-price"
+    "path": "/storefront-development/products/price/examples/tax-price"
   },
   {
     "title": "createCartWorkflow",

www/packages/tags/src/utils/generate-tags.ts

@@ -6,25 +6,51 @@ import { findPageTitle, getFrontMatterSync } from "docs-utils"
 
 type ConfigItem = {
   path: string
-  contentPaths: string[]
+  contentPaths: {
+    path: string
+    omitFromPath?: boolean
+  }[]
 }
 
 const config: ConfigItem[] = [
   {
     path: path.resolve("..", "..", "apps", "book"),
-    contentPaths: ["app"],
+    contentPaths: [
+      {
+        path: "app",
+        omitFromPath: true,
+      },
+    ],
   },
   {
     path: path.resolve("..", "..", "apps", "resources"),
-    contentPaths: ["app", "references"],
+    contentPaths: [
+      {
+        path: "app",
+        omitFromPath: true,
+      },
+      {
+        path: "references",
+      },
+    ],
   },
   {
     path: path.resolve("..", "..", "apps", "ui"),
-    contentPaths: [path.join("src", "content", "docs")],
+    contentPaths: [
+      {
+        path: path.join("src", "content", "docs"),
+        omitFromPath: true,
+      },
+    ],
   },
   {
     path: path.resolve("..", "..", "apps", "user-guide"),
-    contentPaths: ["app"],
+    contentPaths: [
+      {
+        path: "app",
+        omitFromPath: true,
+      },
+    ],
   },
 ]
 
@@ -47,20 +73,21 @@ export async function generateTags(basePath?: string) {
   basePath = basePath || path.resolve()
   const tags: Tags = {}
   async function getTags(item: ConfigItem) {
-    async function scanDirectory(dirPath: string) {
-      const files = await readdir(dirPath)
+    async function scanDirectory(currentDirPath: string, omitPath?: string) {
+      const files = await readdir(currentDirPath)
 
       for (const file of files) {
-        const fullPath = path.join(dirPath, file)
+        const fullPath = path.join(currentDirPath, file)
         if (!file.endsWith(".mdx") || file.startsWith("_")) {
           if (statSync(fullPath).isDirectory()) {
-            await scanDirectory(fullPath)
+            await scanDirectory(fullPath, omitPath)
           }
           continue
         }
 
         const frontmatter = getFrontMatterSync(fullPath)
         const fileBasename = path.basename(file)
+        const itemBasePath = path.join(item.path, omitPath || "")
 
         frontmatter.tags?.forEach((tag) => {
           if (!Object.hasOwn(tags, tag)) {
@@ -73,16 +100,21 @@ export async function generateTags(basePath?: string) {
             ),
             path:
               frontmatter.slug ||
-              fullPath.replace(item.path, "").replace(`/${fileBasename}`, ""),
+              fullPath
+                .replace(itemBasePath, "")
+                .replace(`/${fileBasename}`, ""),
           })
         })
       }
     }
 
     for (const contentPath of item.contentPaths) {
-      const basePath = path.join(item.path, contentPath)
+      const basePath = path.join(item.path, contentPath.path)
 
-      await scanDirectory(basePath)
+      await scanDirectory(
+        basePath,
+        !contentPath.omitFromPath ? "" : contentPath.path
+      )
     }
   }
 

www/packages/types/src/sidebar.ts

@@ -16,7 +16,7 @@ export type SidebarItemCommon = {
 }
 
 export type SidebarItemLink = SidebarItemCommon & {
-  type: "link"
+  type: "link" | "ref"
   path: string
   isPathHref?: boolean
   linkProps?: React.AllHTMLAttributes<HTMLAnchorElement>
@@ -59,9 +59,18 @@ export type SidebarSectionItems = {
 export type RawSidebarItem = SidebarItem & {
   autogenerate_path?: string
   autogenerate_tags?: string
+  autogenerate_as_ref?: boolean
   custom_autogenerate?: string
   number?: string
-}
+} & (
+    | {
+        type: "category" | "sub-category" | "link" | "ref"
+        children?: RawSidebarItem[]
+      }
+    | {
+        type: "separator"
+      }
+  )
 
 export type PersistedSidebarCategoryState = {
   [k: string]: {