docs: changes to main docs sidebar (#11750)

* docs: changes to main docs sidebar

* fix links

* fix vale test

* fix vale errors

.github/workflows/docs-test.yml

@@ -88,7 +88,7 @@ jobs:
       - name: Get Directories to Scan
         if: ${{ steps.pr-files.outputs.files_lt_threshold == 'true' }}
         working-directory: www/vale
-        run: ./get-files.sh book app
+        run: ./get-files.sh book/app/learn resources
         id: directories
 
       - name: Vale Linter
@@ -145,7 +145,7 @@ jobs:
 
       - name: Get Directories to Scan
         working-directory: www/vale
-        run: ./get-files.sh resources app contribution-guidelines usage
+        run: ./get-files.sh resources/app
         id: directories
 
       - name: Vale Linter
@@ -202,7 +202,7 @@ jobs:
 
       - name: Get Directories to Scan
         working-directory: www/vale
-        run: ./get-files.sh user-guide app
+        run: ./get-files.sh user-guide/app
         id: directories
 
       - name: Vale Linter
@@ -260,7 +260,7 @@ jobs:
       - name: Get Directories to Scan
         if: ${{ steps.pr-files.outputs.files_lt_threshold == 'true' }}
         working-directory: www/vale
-        run: ./get-files.sh ui src/content/docs
+        run: ./get-files.sh ui/src/content/docs
         id: directories
 
       - name: Vale Linter
@@ -318,7 +318,7 @@ jobs:
       - name: Get Directories to Scan
         if: ${{ steps.pr-files.outputs.files_lt_threshold == 'true' }}
         working-directory: www/vale
-        run: ./get-files.sh api-reference markdown
+        run: ./get-files.sh api-reference/markdown
         id: directories
 
       - name: Vale Linter

www/apps/book/app/learn/debugging-and-testing/page.mdx

@@ -1,12 +0,0 @@
-export const metadata = {
-  title: `${pageNumber} Debugging and Testing`,
-}
-
-# {metadata.title}
-
-In the next chapters, you’ll learn about the tools Medusa provides for testing and debugging your Medusa application.
-
-By the end of this chapter, you’ll learn:
-
-- How to use Medusa's `@medusajs/test-utils` test to write integration tests.
-- How to use Medusa’s `Logger` utility to log messages.

www/apps/book/app/learn/fundamentals/admin/tips/page.mdx

@@ -156,4 +156,4 @@ In your admin customizations, you can use the following global variables:
 
 The Medusa Admin dashboard can be displayed in languages other than English, which is the default. Other languages are added through community contributions.
 
-Learn how to add a new language translation for the Medusa Admin in [this guide](!resources!/contribution-guidelines/admin-translations).
+Learn how to add a new language translation for the Medusa Admin in [this guide](../../../resources/contribution-guidelines/admin-translations/page.mdx).

www/apps/book/app/learn/fundamentals/environment-variables/page.mdx

@@ -226,7 +226,7 @@ You should opt for setting configurations in `medusa-config.ts` where possible.
     <Table.Row>
       <Table.Cell>`MEDUSA_DISABLE_TELEMETRY`</Table.Cell>
       <Table.Cell>
-        Whether to disable analytics data collection. Learn more in [this documenation](!resources!/usage).
+        Whether to disable analytics data collection. Learn more in [this documenation](../../resources/usage/page.mdx).
       </Table.Cell>
       <Table.Cell> \- </Table.Cell>
     </Table.Row>

www/apps/book/app/learn/more-resources/page.mdx

@@ -1,9 +0,0 @@
-export const metadata = {
-  title: `${pageNumber} More Resources`,
-}
-
-# {metadata.title}
-
-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 Development Resources documentation [here](!resources!).

www/apps/book/app/learn/resources/contribution-guidelines/docs/page.mdx

@@ -147,11 +147,15 @@ cd www/vale
 
 ```bash
 # to lint content for the main documentation
-./run-vale.sh docs content error references
+./run-vale.sh book/app/learn error resources
+# to lint content for the resources documentation
+./run-vale.sh resources/app error
 # to lint content for the API reference
-./run-vale.sh api-reference app/_mdx error
+./run-vale.sh api-reference/markdown error
 # to lint content for the Medusa UI documentation
-./run-vale.sh ui src/content/docs error
+./run-vale.sh ui/src/content/docs error
+# to lint content for the user guide
+./run-vale.sh user-guide/app error
 ```
 
 {/* TODO need to enable MDX v1 comments first. */}

www/apps/book/config/index.ts

@@ -14,8 +14,5 @@ export const config: DocsConfig = {
     title: "Documentation",
     key: "book",
   },
-  breadcrumbOptions: {
-    showCategories: false,
-  },
   logo: `${process.env.NEXT_PUBLIC_BASE_PATH}/images/logo.png`,
 }

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

@@ -7,14 +7,12 @@ export const generatedEditDates = {
   "app/learn/fundamentals/workflows/retry-failed-steps/page.mdx": "2024-12-04T07:37:59.823Z",
   "app/learn/fundamentals/workflows/workflow-hooks/page.mdx": "2024-12-09T10:44:33.781Z",
   "app/learn/debugging-and-testing/logging/page.mdx": "2024-09-30T08:43:53.135Z",
-  "app/learn/more-resources/page.mdx": "2024-07-04T17:26:03+03:00",
   "app/learn/storefront-development/page.mdx": "2024-12-10T09:11:04.993Z",
   "app/learn/storefront-development/nextjs-starter/page.mdx": "2024-12-10T09:05:18.960Z",
   "app/learn/fundamentals/page.mdx": "2024-07-04T17:26:03+03:00",
   "app/learn/fundamentals/admin-customizations/page.mdx": "2024-10-07T12:41:39.218Z",
   "app/learn/fundamentals/workflows/workflow-timeout/page.mdx": "2024-10-21T13:30:21.372Z",
   "app/learn/fundamentals/workflows/parallel-steps/page.mdx": "2024-12-09T14:45:13.801Z",
-  "app/learn/debugging-and-testing/page.mdx": "2024-05-03T17:36:38+03:00",
   "app/learn/fundamentals/medusa-container/page.mdx": "2024-12-09T11:02:38.225Z",
   "app/learn/fundamentals/api-routes/page.mdx": "2024-12-04T11:02:57.134Z",
   "app/learn/fundamentals/modules/modules-directory-structure/page.mdx": "2024-12-09T10:32:46.839Z",
@@ -50,7 +48,7 @@ export const generatedEditDates = {
   "app/learn/fundamentals/scheduled-jobs/execution-number/page.mdx": "2024-10-21T13:30:21.371Z",
   "app/learn/fundamentals/api-routes/parameters/page.mdx": "2025-02-14T08:34:03.184Z",
   "app/learn/fundamentals/api-routes/http-methods/page.mdx": "2024-10-21T13:30:21.367Z",
-  "app/learn/fundamentals/admin/tips/page.mdx": "2025-02-24T09:52:06.901Z",
+  "app/learn/fundamentals/admin/tips/page.mdx": "2025-03-06T07:30:06.322Z",
   "app/learn/fundamentals/api-routes/cors/page.mdx": "2024-12-09T13:04:04.357Z",
   "app/learn/fundamentals/admin/ui-routes/page.mdx": "2025-02-24T09:35:11.752Z",
   "app/learn/fundamentals/api-routes/middlewares/page.mdx": "2025-03-04T10:16:15.029Z",
@@ -102,7 +100,7 @@ export const generatedEditDates = {
   "app/learn/introduction/architecture/page.mdx": "2025-01-16T10:25:10.780Z",
   "app/learn/fundamentals/data-models/infer-type/page.mdx": "2024-12-09T15:54:08.713Z",
   "app/learn/fundamentals/custom-cli-scripts/seed-data/page.mdx": "2024-12-09T14:38:06.385Z",
-  "app/learn/fundamentals/environment-variables/page.mdx": "2025-02-18T15:29:37.717Z",
+  "app/learn/fundamentals/environment-variables/page.mdx": "2025-03-06T07:30:22.986Z",
   "app/learn/build/page.mdx": "2024-12-09T11:05:17.383Z",
   "app/learn/deployment/general/page.mdx": "2025-02-24T07:38:02.164Z",
   "app/learn/fundamentals/workflows/multiple-step-usage/page.mdx": "2024-11-25T16:19:32.169Z",
@@ -118,5 +116,8 @@ export const generatedEditDates = {
   "app/learn/fundamentals/module-links/query-context/page.mdx": "2025-02-12T16:59:20.963Z",
   "app/learn/fundamentals/admin/environment-variables/page.mdx": "2025-02-18T14:48:17.731Z",
   "app/learn/fundamentals/api-routes/parse-body/page.mdx": "2025-02-14T08:32:25.596Z",
-  "app/learn/fundamentals/admin/routing/page.mdx": "2025-02-24T09:50:37.495Z"
+  "app/learn/fundamentals/admin/routing/page.mdx": "2025-02-24T09:50:37.495Z",
+  "app/learn/resources/contribution-guidelines/admin-translations/page.mdx": "2025-02-11T16:57:46.726Z",
+  "app/learn/resources/contribution-guidelines/docs/page.mdx": "2025-03-06T09:32:26.010Z",
+  "app/learn/resources/usage/page.mdx": "2025-02-26T13:35:34.824Z"
 }

www/apps/book/generated/sidebar.mjs

@@ -1,7 +1,9 @@
 export const generatedSidebar = [
   {
+    "loaded": true,
+    "isPathHref": true,
     "type": "category",
-    "title": "1. Introduction",
+    "title": "1. Get Started",
     "children": [
       {
         "loaded": true,
@@ -9,38 +11,35 @@ export const generatedSidebar = [
         "type": "link",
         "path": "/learn",
         "title": "Introduction",
-        "children": [
+        "children": [],
-          {
+        "chapterTitle": "1.1. Introduction"
-            "loaded": true,
+      },
-            "isPathHref": true,
+      {
-            "type": "link",
+        "loaded": true,
-            "path": "/learn/installation",
+        "isPathHref": true,
-            "title": "Installation",
+        "type": "link",
-            "children": [],
+        "path": "/learn/installation",
-            "chapterTitle": "1.1. Installation"
+        "title": "Installation",
-          },
+        "children": [],
-          {
+        "chapterTitle": "1.2. Installation"
-            "loaded": true,
+      },
-            "isPathHref": true,
+      {
-            "type": "link",
+        "loaded": true,
-            "title": "Architecture",
+        "isPathHref": true,
-            "path": "/learn/introduction/architecture",
+        "type": "link",
-            "children": [],
+        "title": "Architecture",
-            "chapterTitle": "1.2. Architecture"
+        "path": "/learn/introduction/architecture",
-          }
+        "children": [],
-        ],
+        "chapterTitle": "1.3. Architecture"
-        "childrenSameLevel": true,
-        "chapterTitle": "1. Introduction"
       }
     ],
-    "loaded": true,
+    "chapterTitle": "1. Get Started"
-    "initialOpen": false
   },
   {
     "loaded": true,
     "isPathHref": true,
     "type": "category",
-    "title": "2. Customize",
+    "title": "2. Customization Tutorial",
     "children": [
       {
         "loaded": true,
@@ -200,13 +199,13 @@ export const generatedSidebar = [
         "chapterTitle": "2.6. Next Steps"
       }
     ],
-    "chapterTitle": "2. Customize"
+    "chapterTitle": "2. Customization Tutorial"
   },
   {
     "loaded": true,
     "isPathHref": true,
     "type": "category",
-    "title": "3. Fundamentals",
+    "title": "3. Framework",
     "children": [
       {
         "loaded": true,
@@ -773,70 +772,6 @@ export const generatedSidebar = [
         ],
         "chapterTitle": "3.8. Scheduled Jobs"
       },
-      {
-        "loaded": true,
-        "isPathHref": true,
-        "type": "link",
-        "path": "/learn/fundamentals/admin",
-        "title": "Admin Development",
-        "children": [
-          {
-            "loaded": true,
-            "isPathHref": true,
-            "type": "link",
-            "path": "/learn/fundamentals/admin/widgets",
-            "title": "Admin Widgets",
-            "children": [],
-            "chapterTitle": "3.9.1. Admin Widgets"
-          },
-          {
-            "loaded": true,
-            "isPathHref": true,
-            "type": "link",
-            "path": "/learn/fundamentals/admin/ui-routes",
-            "title": "Admin UI Routes",
-            "children": [],
-            "chapterTitle": "3.9.2. Admin UI Routes"
-          },
-          {
-            "loaded": true,
-            "isPathHref": true,
-            "type": "link",
-            "path": "/learn/fundamentals/admin/environment-variables",
-            "title": "Environment Variables",
-            "children": [],
-            "chapterTitle": "3.9.3. Environment Variables"
-          },
-          {
-            "loaded": true,
-            "isPathHref": true,
-            "type": "link",
-            "path": "/learn/fundamentals/admin/routing",
-            "title": "Routing Customizations",
-            "children": [],
-            "chapterTitle": "3.9.4. Routing Customizations"
-          },
-          {
-            "loaded": true,
-            "isPathHref": true,
-            "type": "link",
-            "path": "/learn/fundamentals/admin/constraints",
-            "title": "Constraints",
-            "children": [],
-            "chapterTitle": "3.9.5. Constraints"
-          },
-          {
-            "loaded": true,
-            "isPathHref": true,
-            "type": "link",
-            "path": "/learn/fundamentals/admin/tips",
-            "title": "Tips",
-            "children": [],
-            "chapterTitle": "3.9.6. Tips"
-          }
-        ],
-        "chapterTitle": "3.9. Admin Development"
-      },
       {
         "loaded": true,
         "isPathHref": true,
@@ -851,10 +786,10 @@ export const generatedSidebar = [
             "path": "/learn/fundamentals/plugins/create",
             "title": "Create Plugin",
             "children": [],
-            "chapterTitle": "3.10.1. Create Plugin"
+            "chapterTitle": "3.9.1. Create Plugin"
           }
         ],
-        "chapterTitle": "3.10. Plugins"
+        "chapterTitle": "3.9. Plugins"
       },
       {
         "loaded": true,
@@ -870,26 +805,89 @@ export const generatedSidebar = [
             "path": "/learn/fundamentals/custom-cli-scripts/seed-data",
             "title": "Seed Data",
             "children": [],
-            "chapterTitle": "3.11.1. Seed Data"
+            "chapterTitle": "3.10.1. Seed Data"
           }
         ],
-        "chapterTitle": "3.11. Custom CLI Scripts"
+        "chapterTitle": "3.10. Custom CLI Scripts"
+      }
+    ],
+    "chapterTitle": "3. Framework"
+  },
+  {
+    "loaded": true,
+    "isPathHref": true,
+    "type": "category",
+    "title": "4. Admin Development",
+    "children": [
+      {
+        "loaded": true,
+        "isPathHref": true,
+        "type": "link",
+        "path": "/learn/fundamentals/admin",
+        "title": "Overview",
+        "children": [],
+        "chapterTitle": "4.1. Overview"
       },
       {
         "loaded": true,
         "isPathHref": true,
         "type": "link",
-        "title": "Environment Variables",
+        "path": "/learn/fundamentals/admin/widgets",
-        "path": "/learn/fundamentals/environment-variables",
+        "title": "Admin Widgets",
         "children": [],
-        "chapterTitle": "3.12. Environment Variables"
+        "chapterTitle": "4.2. Admin Widgets"
+      },
+      {
+        "loaded": true,
+        "isPathHref": true,
+        "type": "link",
+        "path": "/learn/fundamentals/admin/ui-routes",
+        "title": "Admin UI Routes",
+        "children": [],
+        "chapterTitle": "4.3. Admin UI Routes"
+      },
+      {
+        "loaded": true,
+        "isPathHref": true,
+        "type": "link",
+        "path": "/learn/fundamentals/admin/environment-variables",
+        "title": "Environment Variables",
+        "children": [],
+        "chapterTitle": "4.4. Environment Variables"
+      },
+      {
+        "loaded": true,
+        "isPathHref": true,
+        "type": "link",
+        "path": "/learn/fundamentals/admin/routing",
+        "title": "Routing Customizations",
+        "children": [],
+        "chapterTitle": "4.5. Routing Customizations"
+      },
+      {
+        "loaded": true,
+        "isPathHref": true,
+        "type": "link",
+        "path": "/learn/fundamentals/admin/constraints",
+        "title": "Constraints",
+        "children": [],
+        "chapterTitle": "4.6. Constraints"
+      },
+      {
+        "loaded": true,
+        "isPathHref": true,
+        "type": "link",
+        "path": "/learn/fundamentals/admin/tips",
+        "title": "Tips",
+        "children": [],
+        "chapterTitle": "4.7. Tips"
       }
     ],
-    "chapterTitle": "3. Fundamentals"
+    "chapterTitle": "4. Admin Development"
   },
   {
     "type": "category",
-    "title": "4. Storefront",
+    "title": "5. Storefront",
     "children": [
       {
         "loaded": true,
@@ -897,7 +895,7 @@ export const generatedSidebar = [
         "type": "link",
         "path": "/learn/storefront-development",
         "title": "Storefront Development",
-        "chapterTitle": "4. Storefront",
+        "chapterTitle": "5. Storefront",
         "children": [],
         "childrenSameLevel": true
       }
@@ -909,8 +907,17 @@ export const generatedSidebar = [
     "loaded": true,
     "isPathHref": true,
     "type": "category",
-    "title": "5. Conventions",
+    "title": "6. Configurations",
     "children": [
+      {
+        "loaded": true,
+        "isPathHref": true,
+        "type": "link",
+        "title": "Environment Variables",
+        "path": "/learn/fundamentals/environment-variables",
+        "children": [],
+        "chapterTitle": "6.1. Environment Variables"
+      },
       {
         "loaded": true,
         "isPathHref": true,
@@ -918,107 +925,97 @@ export const generatedSidebar = [
         "title": "Type Aliases",
         "path": "/learn/conventions/ts-aliases",
         "children": [],
-        "chapterTitle": "5.1. Type Aliases"
+        "chapterTitle": "6.2. Type Aliases"
       }
     ],
-    "chapterTitle": "5. Conventions"
+    "chapterTitle": "6. Configurations"
   },
   {
+    "loaded": true,
+    "isPathHref": true,
     "type": "category",
-    "title": "6. Debugging & Testing",
+    "title": "7. Debugging & Testing",
     "children": [
       {
         "loaded": true,
         "isPathHref": true,
         "type": "link",
-        "path": "/learn/debugging-and-testing",
+        "path": "/learn/debugging-and-testing/testing-tools",
-        "title": "Debugging and Testing",
+        "title": "Testing Tools",
-        "chapterTitle": "6. Debugging & Testing",
+        "children": [],
+        "chapterTitle": "7.1. Testing Tools"
+      },
+      {
+        "loaded": true,
+        "isPathHref": true,
+        "type": "link",
+        "path": "/learn/debugging-and-testing/testing-tools/integration-tests",
+        "title": "Integration Tests",
         "children": [
           {
             "loaded": true,
             "isPathHref": true,
             "type": "link",
-            "path": "/learn/debugging-and-testing/testing-tools",
+            "path": "/learn/debugging-and-testing/testing-tools/integration-tests/api-routes",
-            "title": "Testing Tools",
+            "title": "Example: API Routes Tests",
             "children": [],
-            "chapterTitle": "6.1. Testing Tools"
+            "chapterTitle": "7.2.1. Example: API Routes Tests"
           },
           {
             "loaded": true,
             "isPathHref": true,
             "type": "link",
-            "path": "/learn/debugging-and-testing/testing-tools/integration-tests",
+            "path": "/learn/debugging-and-testing/testing-tools/integration-tests/workflows",
-            "title": "Integration Tests",
+            "title": "Example: Workflows Tests",
-            "children": [
-              {
-                "loaded": true,
-                "isPathHref": true,
-                "type": "link",
-                "path": "/learn/debugging-and-testing/testing-tools/integration-tests/api-routes",
-                "title": "Example: API Routes Tests",
-                "children": [],
-                "chapterTitle": "6.2.1. Example: API Routes Tests"
-              },
-              {
-                "loaded": true,
-                "isPathHref": true,
-                "type": "link",
-                "path": "/learn/debugging-and-testing/testing-tools/integration-tests/workflows",
-                "title": "Example: Workflows Tests",
-                "children": [],
-                "chapterTitle": "6.2.2. Example: Workflows Tests"
-              }
-            ],
-            "chapterTitle": "6.2. Integration Tests"
-          },
-          {
-            "loaded": true,
-            "isPathHref": true,
-            "type": "link",
-            "path": "/learn/debugging-and-testing/testing-tools/modules-tests",
-            "title": "Modules Tests",
-            "children": [
-              {
-                "loaded": true,
-                "isPathHref": true,
-                "type": "link",
-                "path": "/learn/debugging-and-testing/testing-tools/modules-tests/module-example",
-                "title": "Example",
-                "children": [],
-                "chapterTitle": "6.3.1. Example"
-              }
-            ],
-            "chapterTitle": "6.3. Modules Tests"
-          },
-          {
-            "loaded": true,
-            "isPathHref": true,
-            "type": "link",
-            "path": "/learn/debugging-and-testing/instrumentation",
-            "title": "Instrumentation",
             "children": [],
-            "chapterTitle": "6.4. Instrumentation"
+            "chapterTitle": "7.2.2. Example: Workflows Tests"
-          },
-          {
-            "loaded": true,
-            "isPathHref": true,
-            "type": "link",
-            "path": "/learn/debugging-and-testing/logging",
-            "title": "Logging",
-            "children": [],
-            "chapterTitle": "6.5. Logging"
           }
         ],
-        "childrenSameLevel": true
+        "chapterTitle": "7.2. Integration Tests"
+      },
+      {
+        "loaded": true,
+        "isPathHref": true,
+        "type": "link",
+        "path": "/learn/debugging-and-testing/testing-tools/modules-tests",
+        "title": "Modules Tests",
+        "children": [
+          {
+            "loaded": true,
+            "isPathHref": true,
+            "type": "link",
+            "path": "/learn/debugging-and-testing/testing-tools/modules-tests/module-example",
+            "title": "Example",
+            "children": [],
+            "chapterTitle": "7.3.1. Example"
+          }
+        ],
+        "chapterTitle": "7.3. Modules Tests"
+      },
+      {
+        "loaded": true,
+        "isPathHref": true,
+        "type": "link",
+        "path": "/learn/debugging-and-testing/instrumentation",
+        "title": "Instrumentation",
+        "children": [],
+        "chapterTitle": "7.4. Instrumentation"
+      },
+      {
+        "loaded": true,
+        "isPathHref": true,
+        "type": "link",
+        "path": "/learn/debugging-and-testing/logging",
+        "title": "Logging",
+        "children": [],
+        "chapterTitle": "7.5. Logging"
       }
     ],
-    "loaded": true,
+    "chapterTitle": "7. Debugging & Testing"
-    "initialOpen": false
   },
   {
     "type": "category",
-    "title": "7. Production",
+    "title": "8. Production",
     "children": [
       {
         "loaded": true,
@@ -1026,7 +1023,7 @@ export const generatedSidebar = [
         "type": "link",
         "path": "/learn/build",
         "title": "Build",
-        "chapterTitle": "7. Production",
+        "chapterTitle": "8. Production",
         "children": [
           {
             "loaded": true,
@@ -1035,7 +1032,7 @@ export const generatedSidebar = [
             "path": "/learn/deployment",
             "title": "Deployment Overview",
             "children": [],
-            "chapterTitle": "7.1. Deployment Overview"
+            "chapterTitle": "8.1. Deployment Overview"
           },
           {
             "loaded": true,
@@ -1044,7 +1041,7 @@ export const generatedSidebar = [
             "path": "/learn/deployment/general",
             "title": "General Deployment",
             "children": [],
-            "chapterTitle": "7.2. General Deployment"
+            "chapterTitle": "8.2. General Deployment"
           }
         ],
         "childrenSameLevel": true
@@ -1054,39 +1051,75 @@ export const generatedSidebar = [
     "initialOpen": false
   },
   {
+    "loaded": true,
+    "isPathHref": true,
     "type": "category",
-    "title": "8. Updates",
+    "title": "9. Upgrade",
     "children": [
       {
         "loaded": true,
         "isPathHref": true,
         "type": "link",
         "path": "/learn/update",
-        "title": "Updating Medusa",
+        "title": "Update Medusa",
-        "chapterTitle": "8. Updates",
         "children": [],
-        "childrenSameLevel": true
+        "chapterTitle": "9.1. Update Medusa"
+      },
+      {
+        "loaded": true,
+        "isPathHref": true,
+        "type": "external",
+        "path": "https://github.com/medusajs/medusa/releases",
+        "title": "Release Notes",
+        "children": [],
+        "chapterTitle": "9.2. Release Notes"
       }
     ],
-    "loaded": true,
+    "chapterTitle": "9. Upgrade"
-    "initialOpen": false
   },
   {
+    "loaded": true,
+    "isPathHref": true,
     "type": "category",
-    "title": "9. More Resources",
+    "title": "10. Resources",
     "children": [
+      {
+        "loaded": true,
+        "isPathHref": true,
+        "type": "sub-category",
+        "title": "Contribution Guidelines",
+        "children": [
+          {
+            "loaded": true,
+            "isPathHref": true,
+            "type": "link",
+            "path": "/resources/contribution-guidelines/docs",
+            "title": "Docs",
+            "children": [],
+            "chapterTitle": "10.1.1. Docs"
+          },
+          {
+            "loaded": true,
+            "isPathHref": true,
+            "type": "link",
+            "path": "/resources//contribution-guidelines/admin-translations",
+            "title": "Admin Translations",
+            "children": [],
+            "chapterTitle": "10.1.2. Admin Translations"
+          }
+        ],
+        "chapterTitle": "10.1. Contribution Guidelines"
+      },
       {
         "loaded": true,
         "isPathHref": true,
         "type": "link",
-        "path": "/learn/more-resources",
+        "path": "/resources/usage",
-        "title": "More Resources",
+        "title": "Usage",
         "children": [],
-        "childrenSameLevel": true,
+        "chapterTitle": "10.2. Usage"
-        "chapterTitle": "9. More Resources"
       }
     ],
-    "loaded": true,
+    "chapterTitle": "10. Resources"
-    "initialOpen": false
   }
 ]

www/apps/book/next.config.mjs

@@ -8,9 +8,9 @@ import {
   pageNumberRehypePlugin,
   crossProjectLinksPlugin,
 } from "remark-rehype-plugins"
-import { sidebar } from "./sidebar.mjs"
 import path from "path"
 import redirects from "./utils/redirects.mjs"
+import { generatedSidebar } from "./generated/sidebar.mjs"
 
 const withMDX = mdx({
   extension: /\.mdx?$/,
@@ -82,7 +82,7 @@ const withMDX = mdx({
       [
         pageNumberRehypePlugin,
         {
-          sidebar: sidebar,
+          sidebar: generatedSidebar,
         },
       ],
     ],

www/apps/book/sidebar.mjs

@@ -3,10 +3,14 @@ import { sidebarAttachHrefCommonOptions } from "./utils/sidebar-attach-common-op
 /** @type {import('@/types').SidebarItem[]} */
 export const sidebar = sidebarAttachHrefCommonOptions([
   {
-    type: "link",
+    type: "category",
-    path: "/learn",
+    title: "Get Started",
-    title: "Introduction",
     children: [
+      {
+        type: "link",
+        path: "/learn",
+        title: "Introduction",
+      },
       {
         type: "link",
         path: "/learn/installation",
@@ -21,7 +25,7 @@ export const sidebar = sidebarAttachHrefCommonOptions([
   },
   {
     type: "category",
-    title: "Customize",
+    title: "Customization Tutorial",
     children: [
       {
         type: "link",
@@ -120,7 +124,7 @@ export const sidebar = sidebarAttachHrefCommonOptions([
   },
   {
     type: "category",
-    title: "Fundamentals",
+    title: "Framework",
     children: [
       {
         type: "link",
@@ -446,43 +450,6 @@ export const sidebar = sidebarAttachHrefCommonOptions([
           },
         ],
       },
-      {
-        type: "link",
-        path: "/learn/fundamentals/admin",
-        title: "Admin Development",
-        children: [
-          {
-            type: "link",
-            path: "/learn/fundamentals/admin/widgets",
-            title: "Admin Widgets",
-          },
-          {
-            type: "link",
-            path: "/learn/fundamentals/admin/ui-routes",
-            title: "Admin UI Routes",
-          },
-          {
-            type: "link",
-            path: "/learn/fundamentals/admin/environment-variables",
-            title: "Environment Variables",
-          },
-          {
-            type: "link",
-            path: "/learn/fundamentals/admin/routing",
-            title: "Routing Customizations",
-          },
-          {
-            type: "link",
-            path: "/learn/fundamentals/admin/constraints",
-            title: "Constraints",
-          },
-          {
-            type: "link",
-            path: "/learn/fundamentals/admin/tips",
-            title: "Tips",
-          },
-        ],
-      },
       {
         type: "link",
         path: "/learn/fundamentals/plugins",
@@ -507,10 +474,46 @@ export const sidebar = sidebarAttachHrefCommonOptions([
           },
         ],
       },
+    ],
+  },
+  {
+    type: "category",
+    title: "Admin Development",
+    children: [
       {
         type: "link",
+        path: "/learn/fundamentals/admin",
+        title: "Overview",
+      },
+      {
+        type: "link",
+        path: "/learn/fundamentals/admin/widgets",
+        title: "Admin Widgets",
+      },
+      {
+        type: "link",
+        path: "/learn/fundamentals/admin/ui-routes",
+        title: "Admin UI Routes",
+      },
+      {
+        type: "link",
+        path: "/learn/fundamentals/admin/environment-variables",
         title: "Environment Variables",
-        path: "/learn/fundamentals/environment-variables",
+      },
+      {
+        type: "link",
+        path: "/learn/fundamentals/admin/routing",
+        title: "Routing Customizations",
+      },
+      {
+        type: "link",
+        path: "/learn/fundamentals/admin/constraints",
+        title: "Constraints",
+      },
+      {
+        type: "link",
+        path: "/learn/fundamentals/admin/tips",
+        title: "Tips",
       },
     ],
   },
@@ -522,8 +525,13 @@ export const sidebar = sidebarAttachHrefCommonOptions([
   },
   {
     type: "category",
-    title: "Conventions",
+    title: "Configurations",
     children: [
+      {
+        type: "link",
+        title: "Environment Variables",
+        path: "/learn/fundamentals/environment-variables",
+      },
       {
         type: "link",
         title: "Type Aliases",
@@ -532,10 +540,8 @@ export const sidebar = sidebarAttachHrefCommonOptions([
     ],
   },
   {
-    type: "link",
+    type: "category",
-    path: "/learn/debugging-and-testing",
+    title: "Debugging & Testing",
-    title: "Debugging and Testing",
-    chapterTitle: "Debugging & Testing",
     children: [
       {
         type: "link",
@@ -602,14 +608,46 @@ export const sidebar = sidebarAttachHrefCommonOptions([
     ],
   },
   {
-    type: "link",
+    type: "category",
-    path: "/learn/update",
+    title: "Upgrade",
-    title: "Updating Medusa",
+    children: [
-    chapterTitle: "Updates",
+      {
+        type: "link",
+        path: "/learn/update",
+        title: "Update Medusa",
+      },
+      {
+        type: "external",
+        path: "https://github.com/medusajs/medusa/releases",
+        title: "Release Notes",
+      },
+    ],
   },
   {
-    type: "link",
+    type: "category",
-    path: "/learn/more-resources",
+    title: "Resources",
-    title: "More Resources",
+    children: [
+      {
+        type: "sub-category",
+        title: "Contribution Guidelines",
+        children: [
+          {
+            type: "link",
+            path: "/resources/contribution-guidelines/docs",
+            title: "Docs",
+          },
+          {
+            type: "link",
+            path: "/resources//contribution-guidelines/admin-translations",
+            title: "Admin Translations",
+          },
+        ],
+      },
+      {
+        type: "link",
+        path: "/resources/usage",
+        title: "Usage",
+      },
+    ],
   },
 ])

www/apps/book/utils/redirects.mjs

@@ -113,6 +113,16 @@ const redirects = async () => {
       destination: "/learn/fundamentals/module-links/link",
       permanent: true,
     },
+    {
+      source: "/learn/debugging-and-testing",
+      destination: "/learn/debugging-and-testing/testing-tools",
+      permanent: true,
+    },
+    {
+      source: "/learn/more-resources",
+      destination: "/learn/resources/contribution-guidelines/docs",
+      permanent: true,
+    },
   ]
 }
 

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

@@ -99,7 +99,6 @@ export const generatedEditDates = {
   "app/commerce-modules/user/user-creation-flows/page.mdx": "2025-02-26T11:35:54.685Z",
   "app/commerce-modules/user/page.mdx": "2025-02-26T11:18:00.382Z",
   "app/commerce-modules/page.mdx": "2024-12-23T14:38:21.064Z",
-  "app/contribution-guidelines/docs/page.mdx": "2024-12-12T11:06:12.250Z",
   "app/create-medusa-app/page.mdx": "2025-01-16T10:00:25.975Z",
   "app/deployment/admin/vercel/page.mdx": "2024-10-16T08:10:29.377Z",
   "app/deployment/medusa-application/railway/page.mdx": "2025-02-24T07:35:43.421Z",
@@ -188,7 +187,6 @@ export const generatedEditDates = {
   "app/troubleshooting/general-errors/page.mdx": "2024-05-03T17:36:38+03:00",
   "app/troubleshooting/s3/page.mdx": "2025-01-24T13:47:24.994Z",
   "app/troubleshooting/page.mdx": "2025-02-26T11:40:54.162Z",
-  "app/usage/page.mdx": "2025-02-26T11:49:39.213Z",
   "app/page.mdx": "2025-02-26T10:23:58.440Z",
   "app/commerce-modules/auth/_events/_events-table/page.mdx": "2024-07-03T19:27:13+03:00",
   "app/commerce-modules/auth/auth-flows/page.mdx": "2025-01-13T11:31:35.361Z",
@@ -3144,7 +3142,6 @@ export const generatedEditDates = {
   "references/product/interfaces/product.FilterableProductProps/page.mdx": "2025-02-24T10:48:41.629Z",
   "references/types/HttpTypes/interfaces/types.HttpTypes.AdminBatchProductVariantRequest/page.mdx": "2024-12-09T13:21:34.309Z",
   "references/types/WorkflowTypes/ProductWorkflow/interfaces/types.WorkflowTypes.ProductWorkflow.ExportProductsDTO/page.mdx": "2025-02-11T11:36:51.281Z",
-  "app/contribution-guidelines/admin-translations/page.mdx": "2024-11-14T08:54:15.369Z",
   "app/integrations/guides/sanity/page.mdx": "2025-02-05T09:10:44.478Z",
   "references/api_key/types/api_key.FindConfigOrder/page.mdx": "2024-11-25T17:49:28.715Z",
   "references/auth/types/auth.FindConfigOrder/page.mdx": "2024-11-25T17:49:28.887Z",

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

@@ -763,14 +763,6 @@ export const filesMap = [
     "filePath": "/www/apps/resources/app/commerce-modules/user/workflows/page.mdx",
     "pathname": "/commerce-modules/user/workflows"
   },
-  {
-    "filePath": "/www/apps/resources/app/contribution-guidelines/admin-translations/page.mdx",
-    "pathname": "/contribution-guidelines/admin-translations"
-  },
-  {
-    "filePath": "/www/apps/resources/app/contribution-guidelines/docs/page.mdx",
-    "pathname": "/contribution-guidelines/docs"
-  },
   {
     "filePath": "/www/apps/resources/app/create-medusa-app/page.mdx",
     "pathname": "/create-medusa-app"
@@ -1267,10 +1259,6 @@ export const filesMap = [
     "filePath": "/www/apps/resources/app/troubleshooting/workflow-errors/page.mdx",
     "pathname": "/troubleshooting/workflow-errors"
   },
-  {
-    "filePath": "/www/apps/resources/app/usage/page.mdx",
-    "pathname": "/usage"
-  },
   {
     "filePath": "/www/apps/resources/references/api_key/IApiKeyModuleService/methods/api_key.IApiKeyModuleService.authenticate/page.mdx",
     "pathname": "/references/api_key/IApiKeyModuleService/methods/api_key.IApiKeyModuleService.authenticate"

www/apps/resources/generated/sidebar.mjs

@@ -7159,6 +7159,14 @@ export const generatedSidebar = [
                         "path": "https://docs.medusajs.com/resources/references/js-sdk/admin/claim",
                         "children": []
                       },
+                      {
+                        "loaded": true,
+                        "isPathHref": true,
+                        "type": "ref",
+                        "title": "draftOrder",
+                        "path": "https://docs.medusajs.com/resources/references/js-sdk/admin/draftOrder",
+                        "children": []
+                      },
                       {
                         "loaded": true,
                         "isPathHref": true,
@@ -25101,45 +25109,5 @@ export const generatedSidebar = [
         ]
       }
     ]
-  },
-  {
-    "loaded": true,
-    "isPathHref": true,
-    "type": "category",
-    "title": "Other",
-    "children": [
-      {
-        "loaded": true,
-        "isPathHref": true,
-        "type": "sub-category",
-        "title": "Contribution Guidelines",
-        "children": [
-          {
-            "loaded": true,
-            "isPathHref": true,
-            "type": "link",
-            "path": "/contribution-guidelines/docs",
-            "title": "Docs",
-            "children": []
-          },
-          {
-            "loaded": true,
-            "isPathHref": true,
-            "type": "link",
-            "path": "/contribution-guidelines/admin-translations",
-            "title": "Admin Translations",
-            "children": []
-          }
-        ]
-      },
-      {
-        "loaded": true,
-        "isPathHref": true,
-        "type": "link",
-        "path": "/usage",
-        "title": "Usage",
-        "children": []
-      }
-    ]
   }
 ]

www/apps/resources/next.config.mjs

@@ -133,6 +133,16 @@ const nextConfig = {
         destination: "/recipes/erp",
         permanent: true,
       },
+      {
+        source: "/contribution-guidelines/:path",
+        destination: `${process.env.NEXT_PUBLIC_BASE_URL}/learn/resources/contribution-guidelines/:path`,
+        permanent: true,
+      },
+      {
+        source: "/usage",
+        destination: `${process.env.NEXT_PUBLIC_BASE_URL}/learn/resources/usage`,
+        permanent: true,
+      },
     ]
   },
   outputFileTracingExcludes: {

www/apps/resources/sidebar.mjs

@@ -212,31 +212,4 @@ export const sidebar = sidebarAttachHrefCommonOptions([
     title: "References",
     children: referencesSidebar,
   },
-  {
-    type: "category",
-    title: "Other",
-    children: [
-      {
-        type: "sub-category",
-        title: "Contribution Guidelines",
-        children: [
-          {
-            type: "link",
-            path: "/contribution-guidelines/docs",
-            title: "Docs",
-          },
-          {
-            type: "link",
-            path: "/contribution-guidelines/admin-translations",
-            title: "Admin Translations",
-          },
-        ],
-      },
-      {
-        type: "link",
-        path: "/usage",
-        title: "Usage",
-      },
-    ],
-  },
 ])

www/apps/user-guide/app/settings/profile/page.mdx

@@ -38,7 +38,7 @@ To edit your profile details and settings:
 
 <Note title="Tip">
 
-Can't find your language? Learn how you can contribute by translating the admin to other languages [here](!resources!/contribution-guidelines/admin-translations).
+Can't find your language? Learn how you can contribute by translating the admin to other languages [here](!docs!/learn/resources/contribution-guidelines/admin-translations).
 
 </Note>
 

www/apps/user-guide/app/tips/languages/page.mdx

@@ -14,7 +14,7 @@ This document covers the complete list of available languages, both official and
 
 <Note>
 
-Can't find your language? Learn how you can contribute by translating the admin to other languages [here](!resources!/contribution-guidelines/admin-translations).
+Can't find your language? Learn how you can contribute by translating the admin to other languages [here](!docs!/learn/resources/contribution-guidelines/admin-translations).
 
 </Note>
 

www/apps/user-guide/generated/edit-dates.mjs

@@ -1,5 +1,5 @@
 export const generatedEditDates = {
-  "app/tips/languages/page.mdx": "2025-02-14T14:16:04.867Z",
+  "app/tips/languages/page.mdx": "2025-03-06T08:49:32.514Z",
   "app/tips/bulk-editor/page.mdx": "2025-02-14T14:16:04.867Z",
   "app/tips/lists/page.mdx": "2025-02-14T14:16:04.867Z",
   "app/settings/sales-channels/page.mdx": "2025-02-19T17:33:55.584Z",
@@ -12,7 +12,7 @@ export const generatedEditDates = {
   "app/orders/page.mdx": "2025-02-17T15:13:42.484Z",
   "app/settings/users/invites/page.mdx": "2025-02-19T11:38:54.009Z",
   "app/settings/developer/page.mdx": "2025-02-25T15:11:55.392Z",
-  "app/settings/profile/page.mdx": "2025-02-25T16:24:21.165Z",
+  "app/settings/profile/page.mdx": "2025-03-06T08:49:28.814Z",
   "app/settings/store/page.mdx": "2025-02-26T10:33:07.346Z",
   "app/products/import/page.mdx": "2025-02-18T12:15:03.830Z",
   "app/products/categories/page.mdx": "2025-02-19T10:21:42.058Z",

www/packages/build-scripts/src/utils/number-sidebar-items.ts

@@ -17,10 +17,12 @@ export default function numberSidebarItems(
     }
 
     // append current number to the item's title
-    item.chapterTitle = `${numbering.join(".")}. ${
+    const currentNumbering = `${numbering.join(".")}.`
+    item.chapterTitle = `${currentNumbering} ${
       item.chapterTitle?.trim() || item.title?.trim()
     }`
     item.title = item.title.trim()
+    item.number = currentNumbering
 
     if (isTopItems) {
       // Add chapter category

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

@@ -87,10 +87,6 @@ export const Breadcrumbs = () => {
             ""
         )
       }
-      tempBreadcrumbItems.set(
-        getLinkPath(sidebarActiveItem) || "/",
-        sidebarActiveItem.chapterTitle || sidebarActiveItem.title || ""
-      )
     }
 
     return tempBreadcrumbItems

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

@@ -119,6 +119,8 @@ export const SidebarItemLink = ({
             "flex justify-between items-center gap-[6px]",
             className
           )}
+          target={item.type === "external" ? "_blank" : undefined}
+          rel={item.type === "external" ? "noopener noreferrer" : undefined}
           {...item.linkProps}
         >
           <span

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

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

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

@@ -21,7 +21,7 @@ import {
   InteractiveSidebarItem,
   SidebarItemCategory,
   SidebarItemLinkWithParent,
-  SidebarItemTypes,
+  InteractiveSidebarItemTypes,
 } from "types"
 import { useIsBrowser } from "../BrowserProvider"
 
@@ -71,7 +71,7 @@ export const SidebarContext = createContext<SidebarContextType | null>(null)
 export type ActionOptionsType = {
   section?: SidebarItemSections
   parent?: {
-    type: SidebarItemTypes
+    type: InteractiveSidebarItemTypes
     path: string
     title: string
     changeLoaded?: boolean

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

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

www/packages/types/src/sidebar.ts

@@ -13,14 +13,21 @@ export type SidebarItemCommon = {
   additionalElms?: React.ReactNode
   chapterTitle?: string
   hideChildren?: boolean
+  // generated by scripts
+  number?: string
   // can be used to hold any description relevant when showing cards, etc...
   description?: string
 }
 
-export type SidebarItemTypes = "category" | "sub-category" | "link" | "ref"
+export type InteractiveSidebarItemTypes =
+  | "category"
+  | "sub-category"
+  | "link"
+  | "ref"
+  | "external"
 
 export type SidebarItemLink = SidebarItemCommon & {
-  type: "link" | "ref"
+  type: "link" | "ref" | "external"
   path: string
   isPathHref?: boolean
   linkProps?: React.AllHTMLAttributes<HTMLAnchorElement>
@@ -68,7 +75,7 @@ export type RawSidebarItem = SidebarItem & {
   number?: string
 } & (
     | {
-        type: "category" | "sub-category" | "link" | "ref"
+        type: InteractiveSidebarItemTypes
         children?: RawSidebarItem[]
       }
     | {

www/vale/get-files.sh

@@ -2,8 +2,8 @@
 
 list=""
 app="www/"
-path="../apps/$1/$2"
+path="../apps/$1"
-exceptions=("${@:3}")
+exceptions=("${@:2}")
 exceptionsCommand=""
 
 for index in ${!exceptions[@]}

www/vale/run-vale.sh

@@ -2,9 +2,9 @@
 
 list=""
 app="www/"
-path="../apps/$1/$2"
+path="../apps/$1"
-alertLevel=$3
+alertLevel=$2
-exceptions=("${@:4}")
+exceptions=("${@:3}")
 exceptionsCommand=""
 
 for index in ${!exceptions[@]}