docs: improved glossary feature (#4819)

www/docs/content/glossary.mdx

@@ -0,0 +1,11 @@
+---
+description: "Learn about the different terms related to Medusa"
+---
+
+import Glossary from "@site/src/components/Glossary"
+
+# Glossary
+
+Find definitions of different basic terms in the Medusa documentation.
+
+<Glossary />

www/docs/sidebars.js

@@ -360,6 +360,15 @@ module.exports = {
       },
       className: "homepage-sidebar-item",
     },
+    {
+      type: "doc",
+      id: "glossary",
+      label: "Glossary",
+      customProps: {
+        sidebar_icon: "book-open",
+      },
+      className: "homepage-sidebar-item",
+    },
     {
       type: "doc",
       id: "usage",

www/docs/src/components/Glossary/index.tsx

@@ -0,0 +1,50 @@
+import React, { useMemo } from "react"
+import Heading from "@theme/Heading"
+import { GlossaryType, getGlossary } from "../../utils/glossary"
+import Link from "@docusaurus/Link"
+
+type GlossaryProps = React.HTMLAttributes<HTMLDivElement>
+
+type GroupedGlossary = {
+  [letter: string]: GlossaryType[]
+}
+
+const Glossary: React.FC<GlossaryProps> = (props) => {
+  const groupedGlossary: GroupedGlossary = useMemo(() => {
+    const glossary = getGlossary()
+    glossary.sort((a, b) => {
+      return a.title.localeCompare(b.title)
+    })
+    const grouped: GroupedGlossary = {}
+    glossary.forEach((glossaryItem) => {
+      const firstChar = glossaryItem.title.charAt(0).toLowerCase()
+      grouped[firstChar] = [...(grouped[firstChar] || []), glossaryItem]
+    })
+
+    return grouped
+  }, [])
+
+  return (
+    <div {...props}>
+      {Object.entries(groupedGlossary).map(([letter, glossary], index) => (
+        <React.Fragment key={index}>
+          <Heading id={letter.toLowerCase()} as="h2">
+            {letter.toUpperCase()}
+          </Heading>
+          <ul>
+            {glossary.map((glossaryItem, index) => (
+              <li key={index}>
+                <Link to={glossaryItem.referenceLink}>
+                  {glossaryItem.title}
+                </Link>
+                : {glossaryItem.content}
+              </li>
+            ))}
+          </ul>
+        </React.Fragment>
+      ))}
+    </div>
+  )
+}
+
+export default Glossary

www/docs/src/components/LearningPath/index.tsx

@@ -1,5 +1,5 @@
 import { useLearningPath } from "@site/src/providers/LearningPath"
-import { useNotifications } from "@site/src/providers/NotificationProvider"
+import { useNotifications } from "@site/src/providers/Notification"
 import { getLearningPath } from "@site/src/utils/learning-paths"
 import clsx from "clsx"
 import React from "react"

www/docs/src/components/Notification/Container/index.tsx

@@ -1,7 +1,7 @@
 import {
   NotificationItemType,
   useNotifications,
-} from "@site/src/providers/NotificationProvider"
+} from "@site/src/providers/Notification"
 import React from "react"
 import NotificationItem from "../Item"
 import { CSSTransition, TransitionGroup } from "react-transition-group"

www/docs/src/hooks/use-current-learning-path.tsx

@@ -1,6 +1,6 @@
 import React, { useEffect } from "react"
 import { useLearningPath } from "../providers/LearningPath"
-import { useNotifications } from "../providers/NotificationProvider"
+import { useNotifications } from "../providers/Notification"
 import LearningPathSteps from "../components/LearningPath/Steps"
 import LearningPathFinish from "../components/LearningPath/Finish"
 import LearningPathIcon from "../components/LearningPath/Icon"

www/docs/src/hooks/use-onboarding.tsx

@@ -1,6 +1,6 @@
 import React, { useEffect, useState } from "react"
 import { useQueryStringValue } from "@docusaurus/theme-common/internal"
-import { useNotifications } from "../providers/NotificationProvider"
+import { useNotifications } from "../providers/Notification"
 import Rating from "../components/Rating"
 import { useUser } from "../providers/User"
 

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

@@ -17,7 +17,7 @@ import SearchMetadata from "@theme/SearchMetadata"
 import type { Props } from "@theme/DocPage"
 import LearningPathProvider from "@site/src/providers/LearningPath"
 import SidebarProvider from "@site/src/providers/Sidebar"
-import NotificationProvider from "@site/src/providers/NotificationProvider"
+import NotificationProvider from "@site/src/providers/Notification"
 import UserProvider from "@site/src/providers/User"
 import ModalProvider from "../../providers/Modal"
 

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

@@ -1,4 +1,4 @@
-import React from "react"
+import React, { useMemo } from "react"
 import type { Props } from "@theme/MDXComponents/A"
 import { getGlossaryByPath } from "../../utils/glossary"
 import useDocusaurusContext from "@docusaurus/useDocusaurusContext"
@@ -14,10 +14,12 @@ const MDXA = (props: Props) => {
   } = useDocusaurusContext() as MedusaDocusaurusContext
 
   // check if a glossary exists for href
-  const glossary =
+  const glossary = useMemo(() => {
-    (typeof children === "string" && href.startsWith("/")) || href.includes(url)
+    return (typeof children === "string" && href.startsWith("/")) ||
+      href.includes(url)
       ? getGlossaryByPath(children as string)
       : null
+  }, [href, children])
 
   if (!glossary) {
     return <Link {...props} />

www/docs/src/utils/glossary.ts

@@ -1,8 +1,9 @@
-type GlossaryType = {
+export type GlossaryType = {
   matchTextRegex: RegExp
   ignoreTextRegex?: RegExp
   title: string
   content: string
+  referenceLink: string
 }
 
 const glossary: GlossaryType[] = [
@@ -10,38 +11,45 @@ const glossary: GlossaryType[] = [
     title: "Migration",
     content: "A script that is used to reflect changes to the database schema.",
     matchTextRegex: /migration/i,
+    referenceLink: "/development/entities/migrations/overview",
   },
   {
     title: "Repository",
     content:
       "A class that provides generic methods to retrieve and manipulate entities.",
     matchTextRegex: /(repository|repositories)/i,
+    referenceLink: "/development/entities/repositories",
   },
   {
     title: "Entity",
     content: "A class that represents a table in the database.",
     matchTextRegex: /(entity|entities)/i,
+    referenceLink: "/development/entities/overview",
   },
   {
     title: "Dependency Injection",
     content: "The act of delivering the required resources to a class",
     matchTextRegex: /(dependency injection|dependency-injection)/i,
+    referenceLink: "/development/fundamentals/dependency-injection",
   },
   {
     title: "Middleware",
     content:
       "A function that can be executed before or after endpoint requests are handled.",
     matchTextRegex: /middleware/i,
+    referenceLink: "/development/endpoints/add-middleware",
   },
   {
     title: "Endpoint",
     content: "REST API exposed to frontends or external systems.",
     matchTextRegex: /endpoint/i,
+    referenceLink: "/development/endpoints/overview",
   },
   {
     title: "Subscriber",
     content: "A class that registers handler methods to an event.",
     matchTextRegex: /subscriber/i,
+    referenceLink: "/development/events/subscribers",
   },
   {
     title: "Module",
@@ -49,57 +57,67 @@ const glossary: GlossaryType[] = [
       "Reusable pieces of code that provide specific functionality or feature.",
     matchTextRegex: /module/,
     ignoreTextRegex: /commerce module/i,
+    referenceLink: "/development/modules/overview",
   },
   {
     title: "Loader",
     content: "A script that runs when the Medusa backend starts.",
     matchTextRegex: /loader/i,
+    referenceLink: "/development/loaders/overview",
   },
   {
     title: "Scheduled Job",
     content:
       "A task that is performed at specific times during the Medusa backend's runtime.",
     matchTextRegex: /scheduled job/i,
+    referenceLink: "/development/scheduled-jobs/overview",
   },
   {
     title: "Batch Job",
     content: "A task that is performed asynchronously and iteratively.",
     matchTextRegex: /batch job/i,
+    referenceLink: "/development/batch-jobs",
   },
   {
     title: "Strategy",
     content:
       "A class that contains an isolated piece of logic that can be overridden and customized",
     matchTextRegex: /(strategy|strategies)/i,
+    referenceLink: "/development/strategies/overview",
   },
   {
     title: "Feature Flag",
     content: "Guards beta features in the Medusa backend.",
     matchTextRegex: /(feature-flag|feature flag)/i,
+    referenceLink: "/development/feature-flags/overview",
   },
   {
     title: "Idempotency Key",
     content:
       "A unique, randomly-generated key associated with a process, such as cart completion.",
     matchTextRegex: /(idempotency-key|idempotency key)/i,
+    referenceLink: "/development/idempotency-key/overview",
   },
   {
     title: "Search Service",
     content:
       "A class that implements an interface to provide search functionalities.",
     matchTextRegex: /(search service|search-service)/i,
+    referenceLink: "/development/search/overview",
   },
   {
     title: "File Service",
     content:
       "A class that implements an interface to provide storage functionalities.",
     matchTextRegex: /(file service|file-service)/i,
+    referenceLink: "/development/file-service/overview",
   },
   {
     title: "Notification Service",
     content:
       "A class that implements an interface to provide notification functionalities.",
     matchTextRegex: /(notification service|notification-service)/i,
+    referenceLink: "/development/notification/overview",
   },
   {
     title: "Plugin",
@@ -108,6 +126,7 @@ const glossary: GlossaryType[] = [
     matchTextRegex: /plugin/i,
     ignoreTextRegex:
       /(file-service plugin|file service plugin|notification service plugin|notification-service plugin|search service plugin|search-service plugin)/i,
+    referenceLink: "/development/plugins/overview",
   },
   {
     title: "Service",
@@ -115,42 +134,49 @@ const glossary: GlossaryType[] = [
     matchTextRegex: /service/i,
     ignoreTextRegex:
       /(file-service|file service|notification service|notification-service|search service|search-service)/i,
+    referenceLink: "/development/services/overview",
   },
   {
     title: "Publishable API Key",
     content:
       "An API key that is associated with a set of resources and used on the client (storefront) side.",
     matchTextRegex: /(publishable-api-key|publishable api key)/i,
+    referenceLink: "/development/publishable-api-keys",
   },
   {
     title: "JavaScript Client",
     content:
       "An NPM package that provides methods to interact with the Medusa backend's REST APIs.",
     matchTextRegex: /(js-client|js client|medusa javascript client)/i,
+    referenceLink: "/js-client/overview",
   },
   {
     title: "Medusa React",
     content:
       "An NPM package that provides React hooks and utility methods to interact with the Medusa backend's REST APIs.",
     matchTextRegex: /(medusa-react|medusa react)/i,
+    referenceLink: "/medusa-react/overview",
   },
   {
     title: "Admin Widget",
     content:
       "Custom React components that can be injected into different locations in the Medusa admin dashboard",
     matchTextRegex: /admin widget/i,
+    referenceLink: "/admin/widgets",
   },
   {
     title: "Admin UI Route",
     content:
       "A React component that is used to create a new page in the Medusa admin dashboard.",
     matchTextRegex: /(admin route|admin UI route)/i,
+    referenceLink: "/admin/routes",
   },
   {
     title: "Admin Setting Page",
     content:
       "A React component that is used to create a new setting page in the Medusa admin dashboard",
     matchTextRegex: /admin setting page/i,
+    referenceLink: "/admin/setting-pages",
   },
 ]