docs: change navbar items + breadcrumb improvements (#9209)

- Add a new commerce module navbar item - Rename Learning Resources to Development Resources (in navbar and across documentation content) - Improve breadcrumbs to show categories / subcategories Preview: https://resources-docs-git-docs-navbar-changes-medusajs.vercel.app/v2/resources
2024-09-22 12:47:35 +00:00
parent 0bce09f0a2
commit 138523a629
24 changed files with 146 additions and 39 deletions
@@ -20,7 +20,7 @@ While you can start playing around with Medusa and customize it, it's highly rec

 ## Helpful Resources Guides

-The [Learning Resources](!resources!) documentation provides more helpful guides and references for your development journey.
+The [Development Resources](!resources!) documentation provides more helpful guides and references for your development journey.

 Some of these guides and references are:

@@ -33,6 +33,6 @@ Some of these guides and references are:

 ## More Examples in Recipes

-In the Learning Resources documentation, you'll also find step-by-step guides of different use cases, such as building a marketplace, digital products, and more.
+In the Development Resources documentation, you'll also find step-by-step guides of different use cases, such as building a marketplace, digital products, and more.

 Refer to the [Recipes](!resources!/recipes) documentation to learn more.
@@ -72,7 +72,7 @@ This runs your Medusa application and runs the tests available under the `src/in

 ## Other Options and Inputs

-Refer to [this reference in the Learning Resources documentation](!resources!/test-tools-reference/medusaIntegrationTestRunner) for other available parameter options and inputs of the `testSuite` function.
+Refer to [this reference in the Development Resources documentation](!resources!/test-tools-reference/medusaIntegrationTestRunner) for other available parameter options and inputs of the `testSuite` function.

 ---

@@ -80,7 +80,7 @@ Refer to [this reference in the Learning Resources documentation](!resources!/te

 The `medusaIntegrationTestRunner` function creates a database with a random name before running the tests. Then, it drops that database after all the tests end.

-To manage that database, such as changing its name or perform operations on it in your tests, refer to the [references in the Learning Resources documentation](!resources!/test-tools-reference/medusaIntegrationTestRunner).
+To manage that database, such as changing its name or perform operations on it in your tests, refer to the [references in the Development Resources documentation](!resources!/test-tools-reference/medusaIntegrationTestRunner).

 ---

@@ -121,7 +121,7 @@ moduleIntegrationTestRunner<HelloModuleService>({

 ### Other Options and Inputs

-Refer to [this reference in the Learning Resources documentation](!resources!/test-tools-reference/moduleIntegrationTestRunner) for other available parameter options and inputs of the `testSuite` function.
+Refer to [this reference in the Development Resources documentation](!resources!/test-tools-reference/moduleIntegrationTestRunner) for other available parameter options and inputs of the `testSuite` function.

 ---

@@ -129,4 +129,4 @@ Refer to [this reference in the Learning Resources documentation](!resources!/te

 The `moduleIntegrationTestRunner` function creates a database with a random name before running the tests. Then, it drops that database after all the tests end.

-To manage that database, such as changing its name or perform operations on it in your tests, refer to the [references in the Learning Resources documentation](!resources!/test-tools-reference/moduleIntegrationTestRunner).
+To manage that database, such as changing its name or perform operations on it in your tests, refer to the [references in the Development Resources documentation](!resources!/test-tools-reference/moduleIntegrationTestRunner).
@@ -4,6 +4,6 @@ export const metadata = {

 # {metadata.title}

-The Learning Resources documentation provides guides and references that are useful for your development. This documentation included links to parts of the Learning Resources documentation where necessary.
+The Development Resources documentation provides guides and references that are useful for your development. This documentation included links to parts of the Development Resources documentation where necessary.

-Check out the Learning Resources documentation [here](!resources!).
+Check out the Development Resources documentation [here](!resources!).
@@ -25,7 +25,7 @@ If you think this is a mistake, please [report this issue on GitHub](https://git
      icon: BookOpen
    },
    {
-      title: "Learning Resources",
+      title: "Development Resources",
      href: "!resources!",
      icon: AcademicCapSolid
    },
@@ -104,5 +104,5 @@ By the end of this documentation, you’ll be an expert Medusa developer, leadin
 The documentation for Medusa v2 is split into the following sections:

 1. The main documentation, which is the one you're currently viewing. It's highly recommended to follow all the chapters in this documentation before jumping into other documentation sections.
-2. The [Learning Resources documentation](!resources!) provides guides and resources useful during your development, such as tools, API references, recipes, step-by-step guides and examples, and more.
+2. The [Development Resources documentation](!resources!) provides guides and resources useful during your development, such as tools, API references, recipes, step-by-step guides and examples, and more.
 3. The [Store](!api!/store) and [Admin](!api!/admin) API references provide a reference to the Medusa application's endpoints and instructions related to authentication, parameter types, and more.
@@ -10,7 +10,7 @@ You're free to choose how to build your storefront. You can start with our Next.

 <Note title="Tip">

-To learn how to build a storefront from scratch, check out the [Storefront Development guides](!resources!/storefront-development) in the Learning Resources documentation.
+To learn how to build a storefront from scratch, check out the [Storefront Development guides](!resources!/storefront-development) in the Development Resources documentation.

 </Note>

@@ -51,6 +51,9 @@ export const MainNavProvider = ({ children }: MainNavProviderProps) => {
      navItems={navigationDropdownItems}
      reportIssueLink={reportLink}
      editDate={editDate}
+      breadcrumbOptions={{
+        showCategories: false,
+      }}
    >
      {children}
    </UiMainNavProvider>
@@ -20,7 +20,7 @@ The workspace has the following two directories:

 - `apps`: this directory holds the different documentation websites and projects.
  - `book`: includes the codebase for the Medusa Book. It's built with [Next.js 14](https://nextjs.org/).
-  - `resources`: includes the codebase for the Medusa Learning Resources documentation. It's built with [Next.js 14](https://nextjs.org/).
+  - `resources`: includes the codebase for the Medusa Development Resources documentation. It's built with [Next.js 14](https://nextjs.org/).
  - `api-reference`: includes the codebase for the API reference website. It's built with [Next.js 14](https://nextjs.org/).
  - `ui`: includes the codebase for the Medusa UI documentation website. It's built with [Next.js 14](https://nextjs.org/).
 - `packages`: this directory holds the shared packages and components necessary for the development of the projects in the `apps` directory.
@@ -37,7 +37,7 @@ All documentation projects are built with Next.js. The content is writtin in MDX

 The content of the Medusa Book is placed under the `www/apps/book/app` directory.

-### Medusa Learning Resources Content
+### Medusa Development Resources Content

 The content of the Medusa Resources documentation is placed under the `www/apps/resources/app` directory.

@@ -14,7 +14,7 @@ export const metadata: Metadata = {
    default: config.titleSuffix || "",
  },
  description:
-    "Explore Medusa's recipes, API references, configurations, and more.",
+    "Explore Medusa's recipes, API references, configurations, storefront guides, and more.",
  metadataBase: new URL(
    process.env.NEXT_PUBLIC_BASE_URL || "http://localhost:3000"
  ),
@@ -25,7 +25,7 @@ If you think this is a mistake, please [report this issue on GitHub](https://git
      icon: BookOpen
    },
    {
-      title: "Learning Resources",
+      title: "Development Resources",
      href: "!resources!",
      icon: AcademicCapSolid
    },
@@ -23,7 +23,7 @@ import {
  BuildingsSolid
 } from "@medusajs/icons"

-# Medusa Learning Resources
+# Medusa Development Resources

 Explore Medusa's commerce modules, SDKs, configurations, recipes, and more.

@@ -5,7 +5,7 @@ import { generatedSidebar } from "../generated/sidebar.mjs"
 const baseUrl = process.env.NEXT_PUBLIC_BASE_URL || "http://localhost:3000"

 export const config: DocsConfig = {
-  titleSuffix: "Medusa Learning Resources",
+  titleSuffix: "Medusa Development Resources",
  baseUrl,
  basePath: process.env.NEXT_PUBLIC_BASE_PATH,
  sidebar: {
@@ -23,10 +23,14 @@ export const MainNavProvider = ({ children }: MainNavProviderProps) => {
    () =>
      getNavDropdownItems({
        basePath: config.baseUrl,
-        activePath: basePathUrl(),
+        activePath: basePathUrl(
+          pathname.startsWith("/commerce-modules")
+            ? "/commerce-modules"
+            : undefined
+        ),
        version: "v2",
      }),
-    []
+    [pathname]
  )

  const reportLink = useMemo(
@@ -25,7 +25,7 @@ If you think this is a mistake, please [report this issue on GitHub](https://git
      icon: BookOpen
    },
    {
-      title: "Learning Resources",
+      title: "Development Resources",
      href: "!resources!",
      icon: AcademicCapSolid
    },
@@ -35,7 +35,7 @@ export default function NotFound() {
            icon: BookOpen,
          },
          {
-            title: "Learning Resources",
+            title: "Development Resources",
            href: "!resources!",
            icon: AcademicCapSolid,
          },
@@ -25,7 +25,7 @@ If you think this is a mistake, please [report this issue on GitHub](https://git
      icon: BookOpen
    },
    {
-      title: "Learning Resources",
+      title: "Development Resources",
      href: "!resources!",
      icon: AcademicCapSolid
    },
@@ -0,0 +1,33 @@
+import { IconProps } from "@medusajs/icons/dist/types"
+import React from "react"
+
+export const NavigationDropdownModulesIcon = (props: IconProps) => {
+  return (
+    <svg
+      width="20"
+      height="20"
+      viewBox="0 0 20 20"
+      fill="none"
+      xmlns="http://www.w3.org/2000/svg"
+      {...props}
+    >
+      <rect width="20" height="20" className="fill-medusa-tag-red-icon" />
+      <g clipPath="url(#clip0_10557_13175)">
+        <path
+          d="M14.6448 9.33333C14.8281 9.42539 15.0453 9.41516 15.2192 9.30815C15.3931 9.20034 15.4993 9.0107 15.4993 8.80611V7.43379C15.4993 6.24008 14.5291 5.26985 13.3354 5.26985H11.9387C11.9466 5.20454 11.9584 5.1408 11.9584 5.07313C11.9584 4.2052 11.2525 3.49936 10.3846 3.49936C9.51666 3.49936 8.81082 4.2052 8.81082 5.07313C8.81082 5.1408 8.82263 5.20454 8.8305 5.26985H7.43378C6.24007 5.26985 5.26984 6.24008 5.26984 7.43379V8.83051C5.20453 8.82185 5.14079 8.81084 5.07312 8.81084C4.20519 8.81084 3.49935 9.51667 3.49935 10.3846C3.49935 11.2525 4.20519 11.9584 5.07312 11.9584C5.14079 11.9584 5.20453 11.9466 5.26984 11.9387V13.3354C5.26984 14.5291 6.24007 15.4994 7.43378 15.4994H8.8061C9.01069 15.4994 9.20033 15.3931 9.30814 15.22C9.41515 15.0461 9.42538 14.8281 9.3341 14.6456C9.24833 14.4733 9.20427 14.2978 9.20427 14.1223C9.20427 13.4716 9.73384 12.942 10.3846 12.942C11.0353 12.942 11.5649 13.4716 11.5649 14.1223C11.5649 14.2962 11.5209 14.4725 11.4343 14.6464C11.343 14.8289 11.3533 15.0461 11.4611 15.22C11.5689 15.3939 11.7585 15.4994 11.9631 15.4994H13.3354C14.5291 15.4994 15.4993 14.5291 15.4993 13.3354V11.9631C15.4993 11.7585 15.3931 11.5689 15.2192 11.4611C15.0453 11.3533 14.8273 11.343 14.6448 11.4359C13.8367 11.8411 12.942 11.2116 12.942 10.3854C12.942 9.55916 13.8343 8.92965 14.6448 9.3349V9.33333Z"
+          className="fill-medusa-fg-on-color"
+        />
+      </g>
+      <defs>
+        <clipPath id="clip0_10557_13175">
+          <rect
+            width="12"
+            height="12"
+            className="fill-medusa-fg-on-color"
+            transform="translate(3.5 3.5)"
+          />
+        </clipPath>
+      </defs>
+    </svg>
+  )
+}
@@ -1,13 +1,17 @@
 "use client"

 import React, { useMemo } from "react"
-import { Button, CurrentItemsState, useSidebar } from "../../.."
+import { Button, CurrentItemsState, useMainNav, useSidebar } from "../../.."
 import clsx from "clsx"
 import Link from "next/link"
 import { SidebarItemLink } from "types"

 export const MainNavBreadcrumbs = () => {
  const { currentItems, getActiveItem } = useSidebar()
+  const {
+    activeItem: mainNavActiveItem,
+    breadcrumbOptions: { showCategories },
+  } = useMainNav()

  const getLinkPath = (item?: SidebarItemLink): string | undefined => {
    if (!item) {
@@ -27,14 +31,26 @@ export const MainNavBreadcrumbs = () => {
    const parentPath =
      item.parentItem?.type === "link"
        ? getLinkPath(item.parentItem)
+        : (item.parentItem?.type === "category" && showCategories) ||
+          item.parentItem?.type === "sub-category"
+        ? "#"
        : undefined
    const firstItemPath =
-      item.default[0].type === "link" ? getLinkPath(item.default[0]) : undefined
+      item.default[0].type === "link"
+        ? getLinkPath(item.default[0])
+        : (item.default[0].type === "category" && showCategories) ||
+          item.default[0].type === "sub-category"
+        ? "#"
+        : undefined

-    tempBreadcrumbItems.set(
-      parentPath || firstItemPath || "/",
-      item.parentItem?.childSidebarTitle || item.parentItem?.title || ""
-    )
+    const breadcrumbPath = parentPath || firstItemPath || "/"
+
+    if (!mainNavActiveItem?.path.endsWith(breadcrumbPath)) {
+      tempBreadcrumbItems.set(
+        breadcrumbPath,
+        item.parentItem?.childSidebarTitle || item.parentItem?.title || ""
+      )
+    }

    return tempBreadcrumbItems
  }
@@ -48,10 +64,21 @@ export const MainNavBreadcrumbs = () => {
    }

    const activeItem = getActiveItem()
-    if (activeItem) {
+    if (activeItem && !mainNavActiveItem?.path.endsWith(activeItem.path)) {
+      if (
+        activeItem.parentItem &&
+        (activeItem.parentItem.type !== "category" || showCategories)
+      ) {
+        tempBreadcrumbItems.set(
+          activeItem.parentItem.type === "link"
+            ? getLinkPath(activeItem.parentItem) || "#"
+            : "#",
+          activeItem.parentItem.title || ""
+        )
+      }
      tempBreadcrumbItems.set(
        getLinkPath(activeItem) || "/",
-        activeItem?.title || ""
+        activeItem.title || ""
      )
    }

@@ -70,9 +97,17 @@ export const MainNavBreadcrumbs = () => {
          <span>/</span>
          <Button
            variant="transparent-clear"
-            className="px-docs_0.5 py-docs_0.25"
+            className={clsx(
+              "px-docs_0.5 py-docs_0.25",
+              link === "#" && "hover:!bg-transparent hover:cursor-default"
+            )}
          >
-            <Link href={link}>{title}</Link>
+            <Link
+              href={link}
+              className={clsx(link === "#" && "hover:cursor-default")}
+            >
+              {title}
+            </Link>
          </Button>
        </React.Fragment>
      ))}
@@ -9,6 +9,7 @@ import { NavigationDropdownUiIcon } from "./components/Icons/NavigationDropdown/
 import { NavigationDropdownDocV1Icon } from "./components/Icons/NavigationDropdown/DocV1"
 import { NavigationDropdownUserIcon } from "./components/Icons/NavigationDropdown/User"
 import { NavigationDropdownResourcesIcon } from "./components/Icons/NavigationDropdown/Resources"
+import { NavigationDropdownModulesIcon } from "./components/Icons/NavigationDropdown/Modules"

 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`
@@ -20,11 +21,17 @@ export const navDropdownItemsV2: NavigationDropdownItem[] = [
    icon: NavigationDropdownDocIcon,
    title: "Documentation",
  },
+  {
+    type: "link",
+    path: `/v2/resources/commerce-modules`,
+    icon: NavigationDropdownModulesIcon,
+    title: "Commerce Modules",
+  },
  {
    type: "link",
    path: `/v2/resources`,
    icon: NavigationDropdownResourcesIcon,
-    title: "Learning Resources",
+    title: "Development Resources",
  },
  {
    type: "link",
@@ -1,13 +1,18 @@
 "use client"

 import React, { createContext, useContext, useMemo } from "react"
-import { NavigationDropdownItem } from "types"
+import {
+  BreadcrumbOptions,
+  NavigationDropdownItem,
+  NavigationDropdownItemLink,
+} from "types"

 export type MainNavContext = {
  navItems: NavigationDropdownItem[]
-  activeItem?: NavigationDropdownItem
+  activeItem?: NavigationDropdownItemLink
  reportIssueLink: string
  editDate?: string
+  breadcrumbOptions: BreadcrumbOptions
 }

 const MainNavContext = createContext<MainNavContext | null>(null)
@@ -16,6 +21,7 @@ export type MainNavProviderProps = {
  navItems: NavigationDropdownItem[]
  reportIssueLink: string
  editDate?: string
+  breadcrumbOptions?: BreadcrumbOptions
  children?: React.ReactNode
 }

@@ -24,9 +30,15 @@ export const MainNavProvider = ({
  reportIssueLink,
  children,
  editDate,
+  breadcrumbOptions = {
+    showCategories: true,
+  },
 }: MainNavProviderProps) => {
  const activeItem = useMemo(
-    () => navItems.find((item) => item.type === "link" && item.isActive),
+    () =>
+      navItems.find(
+        (item) => item.type === "link" && item.isActive
+      ) as NavigationDropdownItemLink,
    [navItems]
  )

@@ -37,6 +49,7 @@ export const MainNavProvider = ({
        activeItem,
        reportIssueLink,
        editDate,
+        breadcrumbOptions,
      }}
    >
      {children}
@@ -20,6 +20,7 @@ import {
  SidebarItemLink,
  InteractiveSidebarItem,
  SidebarItemCategory,
+  SidebarItemLinkWithParent,
 } from "types"

 export type CurrentItemsState = SidebarSectionItems & {
@@ -34,7 +35,7 @@ export type SidebarContextType = {
  items: SidebarSectionItems
  currentItems: CurrentItemsState | undefined
  activePath: string | null
-  getActiveItem: () => SidebarItemLink | undefined
+  getActiveItem: () => SidebarItemLinkWithParent | undefined
  setActivePath: (path: string | null) => void
  isLinkActive: (item: SidebarItem, checkChildren?: boolean) => boolean
  isChildrenActive: (item: SidebarItemCategory) => boolean
@@ -100,8 +101,8 @@ const findItem = (
  section: SidebarItem[],
  item: Partial<SidebarItem>,
  checkChildren = true
-): SidebarItemLink | undefined => {
-  let foundItem: SidebarItemLink | undefined
+): SidebarItemLinkWithParent | undefined => {
+  let foundItem: SidebarItemLinkWithParent | undefined
  section.some((i) => {
    if (i.type === "separator") {
      return false
@@ -110,6 +111,9 @@ const findItem = (
      foundItem = i
    } else if (checkChildren && i.children) {
      foundItem = findItem(i.children, item)
+      if (foundItem && !foundItem.parentItem) {
+        foundItem.parentItem = i
+      }
    }

    return foundItem !== undefined
@@ -14,3 +14,7 @@ export type NavigationDropdownItem =
  | {
      type: "divider"
    }
+
+export type BreadcrumbOptions = {
+  showCategories?: boolean
+}
@@ -41,6 +41,10 @@ export type InteractiveSidebarItem =
  | SidebarItemCategory
  | SidebarItemSubCategory

+export type SidebarItemLinkWithParent = SidebarItemLink & {
+  parentItem?: InteractiveSidebarItem
+}
+
 export type SidebarItem = InteractiveSidebarItem | SidebarItemSeparator

 export type SidebarSectionItems = {