add references sidebar

www/apps/resources/app/references-overview/page.mdx

@@ -0,0 +1,11 @@
+import { ChildDocs } from "docs-ui"
+
+export const metadata = {
+  title: `References`,
+}
+
+# {metadata.title}
+
+This section of the documentation holds references related to the Medusa server and admin. These references are useful for your development and customizations. You can find lists of emitted events, Medusa Admin widget injection zones, built-in workflows to use in your customizations, and more.
+
+<ChildDocs hideItems={["Overview"]} defaultItemsPerRow={2} onlyTopLevel />

www/apps/resources/generated/edit-dates.mjs

@@ -6041,5 +6041,6 @@ export const generatedEditDates = {
   "references/core_flows/types/core_flows.ValidateExistingPaymentCollectionStepInput/page.mdx": "2025-03-04T13:33:46.130Z",
   "references/types/interfaces/types.ITaxProvider/page.mdx": "2025-03-04T13:33:52.645Z",
   "app/how-to-tutorials/page.mdx": "2025-03-10T09:33:49.208Z",
-  "app/tools/page.mdx": "2025-03-10T12:38:56.520Z"
+  "app/tools/page.mdx": "2025-03-10T12:38:56.520Z",
+  "app/references-overview/page.mdx": "2025-03-10T12:55:49.803Z"
 }

www/apps/resources/generated/files-map.mjs

@@ -963,6 +963,10 @@ export const filesMap = [
     "filePath": "/www/apps/resources/app/recipes/subscriptions/page.mdx",
     "pathname": "/recipes/subscriptions"
   },
+  {
+    "filePath": "/www/apps/resources/app/references-overview/page.mdx",
+    "pathname": "/references-overview"
+  },
   {
     "filePath": "/www/apps/resources/app/service-factory-reference/methods/create/page.mdx",
     "pathname": "/service-factory-reference/methods/create"

www/apps/resources/sidebar.mjs

@@ -90,27 +90,6 @@ export const sidebar = [
           },
         ],
       },
-      {
-        type: "category",
-        title: "Lists",
-        children: [
-          {
-            type: "link",
-            path: "/medusa-container-resources",
-            title: "Container Dependencies",
-          },
-          {
-            type: "link",
-            path: "/events-reference",
-            title: "Events List",
-          },
-        ],
-      },
-      {
-        type: "category",
-        title: "References",
-        children: referencesSidebar,
-      },
     ],
   },
   {
@@ -138,4 +117,9 @@ export const sidebar = [
     title: "Tools",
     items: toolsSidebar,
   },
+  {
+    sidebar_id: "references",
+    title: "References",
+    items: referencesSidebar,
+  },
 ]

www/apps/resources/sidebars/references.mjs

@@ -1,36 +1,45 @@
 /** @type {import('types').Sidebar.SidebarItem[]} */
 export const referencesSidebar = [
+  {
+    type: "link",
+    path: "/references-overview",
+    title: "Overview",
+  },
+  {
+    type: "separator",
+  },
+  {
+    type: "link",
+    path: "/admin-widget-injection-zones",
+    title: "Admin Widget Injection Zones",
+    description: "List of injection zones you can add widgets in.",
+  },
+  {
+    type: "link",
+    path: "/medusa-container-resources",
+    title: "Container Resources",
+    description:
+      "Resources you can access through the Medusa and Module containers.",
+  },
   {
     type: "sidebar",
-    sidebar_id: "workflows-sdk-reference",
-    title: "Workflows SDK",
-    childSidebarTitle: "Workflows SDK Reference",
-    children: [
-      {
-        type: "link",
-        path: "/references/workflows",
-        title: "Reference Overview",
-      },
-      {
-        type: "separator",
-      },
-      {
-        type: "category",
-        title: "Functions",
-        autogenerate_path: "/references/workflows/functions",
-      },
-    ],
+    sidebar_id: "core-flows",
+    title: "Core Workflows",
+    custom_autogenerate: "core-flows",
+    description:
+      "Built-in workflows and steps you can use in your customizations.",
   },
   {
     type: "sidebar",
     sidebar_id: "dml-reference",
     title: "Data Model Language",
     childSidebarTitle: "Data Model Language Reference",
+    description: "API reference of the Data Model Langauge (DML).",
     children: [
       {
         type: "link",
         path: "/references/data-model",
-        title: "Reference Overview",
+        title: "Overview",
       },
       {
         type: "separator",
@@ -66,15 +75,44 @@ export const referencesSidebar = [
       },
     ],
   },
+  {
+    type: "link",
+    path: "/events-reference",
+    title: "Events",
+    description: "List of events emitted by Medusa's Commerce Modules.",
+  },
+  {
+    type: "sidebar",
+    sidebar_id: "helper-steps-reference",
+    title: "Helper Steps",
+    description: "Steps to query data, emit events, create links, and more.",
+    children: [
+      {
+        type: "link",
+        path: "/references/helper-steps",
+        title: "Overview",
+      },
+      {
+        type: "separator",
+      },
+      {
+        type: "category",
+        title: "Steps",
+        autogenerate_path: "/references/helper_steps/functions",
+      },
+    ],
+  },
   {
     type: "sidebar",
     sidebar_id: "service-factory-reference",
     title: "Service Factory",
+    description:
+      "List of methods in your service extending the service factory.",
     children: [
       {
         type: "link",
         path: "/service-factory-reference",
-        title: "Reference Overview",
+        title: "Overview",
       },
       {
         type: "separator",
@@ -91,41 +129,16 @@ export const referencesSidebar = [
       },
     ],
   },
-  {
-    type: "sidebar",
-    sidebar_id: "helper-steps-reference",
-    title: "Helper Steps",
-    children: [
-      {
-        type: "link",
-        path: "/references/helper-steps",
-        title: "Reference Overview",
-      },
-      {
-        type: "separator",
-      },
-      {
-        type: "category",
-        title: "Steps",
-        autogenerate_path: "/references/helper_steps/functions",
-      },
-    ],
-  },
-  {
-    type: "sidebar",
-    sidebar_id: "core-flows",
-    title: "Core Workflows",
-    custom_autogenerate: "core-flows",
-  },
   {
     type: "sidebar",
     sidebar_id: "test-tools-reference",
     title: "Testing Framework",
+    description: "API reference of functions you can use to write tests.",
     children: [
       {
         type: "link",
         path: "/test-tools-reference",
-        title: "Reference Overview",
+        title: "Overview",
       },
       {
         type: "separator",
@@ -148,4 +161,26 @@ export const referencesSidebar = [
       },
     ],
   },
+  {
+    type: "sidebar",
+    sidebar_id: "workflows-sdk-reference",
+    title: "Workflows SDK",
+    childSidebarTitle: "Workflows SDK Reference",
+    description: "API reference of the Workflow SDK functions and helpers.",
+    children: [
+      {
+        type: "link",
+        path: "/references/workflows",
+        title: "Overview",
+      },
+      {
+        type: "separator",
+      },
+      {
+        type: "category",
+        title: "Functions",
+        autogenerate_path: "/references/workflows/functions",
+      },
+    ],
+  },
 ]

www/apps/resources/utils/get-sidebar-for-path.ts

@@ -56,6 +56,25 @@ const sidebarMappings: {
       "/nextjs-starter",
     ],
   },
+  {
+    module: async () =>
+      import("@/generated/generated-references-sidebar.mjs") as Promise<{
+        default: Sidebar.Sidebar
+      }>,
+    paths: [
+      "/admin-widget-injection-zones",
+      "/medusa-container-resources",
+      "/medusa-workflows-reference",
+      "/references/core-flows",
+      "/references/data-model",
+      "/events-reference",
+      "/references/helper-steps",
+      "/service-factory-reference",
+      "/test-tools-reference",
+      "/references/workflows",
+      "/references-overview",
+    ],
+  },
 ]
 export async function getSidebarForPath(
   currentPath: string

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

@@ -264,27 +264,41 @@ export const useChildDocs = ({
   }, [isBrowser, searchQuery, storageKey, enableSearch])
 
   const getTopLevelElms = (items?: Sidebar.InteractiveSidebarItem[]) => {
+    const itemsToShow: {
+      [k: string]: Sidebar.InteractiveSidebarItem
+    } = {}
+    items?.forEach((childItem) => {
+      const href = isSidebarItemLink(childItem)
+        ? childItem.path
+        : childItem.type === "sidebar"
+          ? getSidebarFirstLinkChild(childItem)?.path
+          : (
+              childItem.children?.find((item) =>
+                isSidebarItemLink(item)
+              ) as Sidebar.SidebarItemLink
+            )?.path
+
+      if (!href) {
+        return
+      }
+
+      itemsToShow[href] = childItem
+    })
+    const itemsToShowEntries = Object.entries(itemsToShow)
+    if (!itemsToShowEntries.length) {
+      return <></>
+    }
     return (
       <CardList
-        items={
-          items?.map((childItem) => {
-            const href = isSidebarItemLink(childItem)
-              ? childItem.path
-              : childItem.children?.length
-                ? (
-                    childItem.children.find((item) =>
-                      isSidebarItemLink(item)
-                    ) as Sidebar.SidebarItemLink
-                  )?.path
-                : "#"
-            return {
-              title: childItem.title,
-              href,
-              rightIcon:
-                childItem.type === "ref" ? ChevronDoubleRight : undefined,
-            }
-          }) || []
-        }
+        items={itemsToShowEntries.map(([href, childItem]) => {
+          return {
+            title: childItem.title,
+            href,
+            rightIcon:
+              childItem.type === "ref" ? ChevronDoubleRight : undefined,
+            text: childItem.description,
+          }
+        })}
         itemsPerRow={itemsPerRow}
         defaultItemsPerRow={defaultItemsPerRow}
       />