docs: revise main docs outline (#10502)

2024-12-09 13:54:42 +02:00
parent c8cb9b5c1a
commit 0ae98c51eb
141 changed files with 814 additions and 1181 deletions
@@ -81,7 +81,7 @@ Afterwards, the installation process will start, which will install the Medusa a

 <Note title="Why is the storefront installed separately?">

-The Medusa application is composed of a headless Node.js server and an admin dashboard. The storefront is installed or custom-built separately and connects to the Medusa application through its REST endpoints, called [API routes](!docs!/learn/basics/api-routes). Learn more about Medusa's architecture in [this documentation](!docs!/learn/advanced-development/architecture/overview).
+The Medusa application is composed of a headless Node.js server and an admin dashboard. The storefront is installed or custom-built separately and connects to the Medusa application through its REST endpoints, called [API routes](!docs!/learn/fundamentals/api-routes). Learn more about Medusa's architecture in [this documentation](!docs!/learn/introduction/architecture).

 </Note>

@@ -154,7 +154,7 @@ Medusa's Notification Module delegates sending notifications to other modules, c

 <Note>

-Learn more about modules in [this documentation](!docs!/learn/basics/modules).
+Learn more about modules in [this documentation](!docs!/learn/fundamentals/modules).

 </Note>

@@ -248,7 +248,7 @@ class ResendNotificationProviderService extends AbstractNotificationProviderServ

 A module's service accepts two parameters:

-1. Dependencies resolved from the [Module's container](!docs!/learn/advanced-development/modules/container), which is the module's local registry that the Medusa application adds framework tools to. In this service, you resolve the [Logger utility](!docs!/learn/debugging-and-testing/logging) from the module's container.
+1. Dependencies resolved from the [Module's container](!docs!/learn/fundamentals/modules/container), which is the module's local registry that the Medusa application adds framework tools to. In this service, you resolve the [Logger utility](!docs!/learn/debugging-and-testing/logging) from the module's container.
 2. The module's options that are passed to the module in Medusa's configuration as you'll see in a later section.

 Using the API key passed in the module's options, you initialize the Resend client. You also set the `options` and `logger` properties.
@@ -627,7 +627,7 @@ Instead, you'll create a subscriber that listens to the `order.placed` event and

 <Note>

-Learn more about Medusa's event system in [this documentation](!docs!/learn/basics/events-and-subscribers).
+Learn more about Medusa's event system in [this documentation](!docs!/learn/fundamentals/events-and-subscribers).

 </Note>

@@ -639,7 +639,7 @@ A workflow is a series of queries and actions, called steps, that complete a tas

 <Note>

-Learn more about workflows in [this documentation](!docs!/learn/basics/workflows)
+Learn more about workflows in [this documentation](!docs!/learn/fundamentals/workflows)

 </Note>

@@ -669,7 +669,7 @@ You define the `sendNotificationStep` using the `createStep` function that accep
 - A string indicating the step's unique name.
 - The step's function definition as a second parameter. It accepts the step's input as a first parameter, and an object of options as a second.

-The `container` property in the second parameter is an instance of the [Medusa container](!docs!/learn/basics/medusa-container), which is a registry of framework and commerce tools, such a module's service, that you can resolve to utilize their functionalities.
+The `container` property in the second parameter is an instance of the [Medusa container](!docs!/learn/fundamentals/medusa-container), which is a registry of framework and commerce tools, such a module's service, that you can resolve to utilize their functionalities.

 <Note title="Tip">

@@ -741,7 +741,7 @@ You create a workflow using the `createWorkflow` function imported from `@medusa

 It accepts as a second parameter a constructor function, which is the workflow's implementation. The workflow has the following steps:

-1. `useQueryGraphStep`, which is a step implemented by Medusa that uses [Query](!docs!/learn/advanced-development/module-links/query), a tool that allows you to retrieve data across modules. You use it to retrieve the order's details.
+1. `useQueryGraphStep`, which is a step implemented by Medusa that uses [Query](!docs!/learn/fundamentals/module-links/query), a tool that allows you to retrieve data across modules. You use it to retrieve the order's details.
 2. `sendNotificationStep` which is the step you implemented. You pass it an array with one object, which is the notification's details having following properties:
    - `to`: The address to send the email to. You pass the customer's email that is stored in the order.
    - `channel`: The channel to send the notification through, which is `email`. Since you specified `email` in the Resend Module Provider's `channel` option, the Notification Module will delegate the sending to the Resend Module Provider's service.
@@ -750,7 +750,7 @@ It accepts as a second parameter a constructor function, which is the workflow's

 <Note title="Tip">

-A workflow's constructor function has some constraints in implementation. Learn more about them in [this documentation](!docs!/learn/advanced-development/workflows/constructor-constraints).
+A workflow's constructor function has some constraints in implementation. Learn more about them in [this documentation](!docs!/learn/fundamentals/workflows/constructor-constraints).

 </Note>

@@ -802,7 +802,7 @@ A subscriber file exports:
 - An asynchronous function that's executed whenever the associated event is emitted, which is the `order.placed` event.
 - A configuration object with an `event` property indicating the event the subscriber is listening to.

-The subscriber function accepts the event's details as a first paramter which has a `data` property that holds the data payload of the event. For example, Medusa emits the `order.placed` event with the order's ID in the data payload. The function also accepts as a second parameter the [Medusa container](!docs!/learn/basics/medusa-container).
+The subscriber function accepts the event's details as a first paramter which has a `data` property that holds the data payload of the event. For example, Medusa emits the `order.placed` event with the order's ID in the data payload. The function also accepts as a second parameter the [Medusa container](!docs!/learn/fundamentals/medusa-container).

 In the function, you execute the `sendOrderConfirmationWorkflow` by invoking it, passing it the `container`, then using its `run` method. The `run` method accepts an object having an `input` property, which is the input to pass to the workflow. You pass the ID of the placed order as received in the event's data payload.

@@ -82,7 +82,7 @@ Afterwards, the installation process will start, which will install the Medusa a

 <Note title="Why is the storefront installed separately?">

-The Medusa application is composed of a headless Node.js server and an admin dashboard. The storefront is installed or custom-built separately and connects to the Medusa application through its REST endpoints, called [API routes](!docs!/learn/basics/api-routes). Learn more about Medusa's architecture in [this documentation](!docs!/learn/advanced-development/architecture/overview).
+The Medusa application is composed of a headless Node.js server and an admin dashboard. The storefront is installed or custom-built separately and connects to the Medusa application through its REST endpoints, called [API routes](!docs!/learn/fundamentals/api-routes). Learn more about Medusa's architecture in [this documentation](!docs!/learn/introduction/architecture).

 </Note>

@@ -138,7 +138,7 @@ In this step, you'll create a Sanity Module that provides the interface to conne

 <Note>

-Learn more about modules in [this documentation](!docs!/learn/basics/modules).
+Learn more about modules in [this documentation](!docs!/learn/fundamentals/modules).

 </Note>

@@ -150,11 +150,11 @@ A module is created under the `src/modules` directory of your Medusa application

 You define a module's functionalities in a service. A service is a TypeScript or JavaScript class that the module exports. In the service's methods, you can connect to the database, which is useful if your module defines tables in the database, or connect to a third-party service.

-Medusa registers the module's service in the [Medusa container](!docs!/learn/basics/medusa-container), allowing you to easily resolve the service from other customizations and use its methods.
+Medusa registers the module's service in the [Medusa container](!docs!/learn/fundamentals/medusa-container), allowing you to easily resolve the service from other customizations and use its methods.

 <Note title="What is the Medusa Container?">

-The Medusa application registers resources, such as a module's service or the [logging tool](!docs!/learn/debugging-and-testing/logging), in the Medusa container so that you can resolve them from other customizations, as you'll see in later sections. Learn more about it in [this documentation](!docs!/learn/basics/medusa-container).
+The Medusa application registers resources, such as a module's service or the [logging tool](!docs!/learn/debugging-and-testing/logging), in the Medusa container so that you can resolve them from other customizations, as you'll see in later sections. Learn more about it in [this documentation](!docs!/learn/fundamentals/medusa-container).

 </Note>

@@ -258,7 +258,7 @@ class SanityModuleService {

 The service's constructor accepts two parameters:

-1. Resources to resolve from the Module's container. A module has a different container than the Medusa application, which you can learn more about it in [this documentation](!docs!/learn/advanced-development/modules/container).
+1. Resources to resolve from the Module's container. A module has a different container than the Medusa application, which you can learn more about it in [this documentation](!docs!/learn/fundamentals/modules/container).
 2. The options passed to the module.

 In the constructor, you create a Sanity client using the `createClient` function imported from `@sanity/client`. You pass it the options that the module receives.
@@ -603,7 +603,7 @@ In the next steps, you'll create a link between the Product and Sanity modules t

 Since a product has a document in Sanity, you want to build an association between the [Product](../../../commerce-modules/product/page.mdx) and Sanity modules so that when you retrieve a product, you also retrieve its associated Sanity document.

-However, modules are [isolated](!docs!/learn/advanced-development/modules/isolation) to ensure they're re-usable and don't have side effects when integrated into the Medusa application. So, to build associations between modules, you define [module links](!docs!/learn/advanced-development/module-links).
+However, modules are [isolated](!docs!/learn/fundamentals/modules/isolation) to ensure they're re-usable and don't have side effects when integrated into the Medusa application. So, to build associations between modules, you define [module links](!docs!/learn/fundamentals/module-links).

 A Module Link associates two modules' data models while maintaining module isolation. A data model can be a table in the database or a virtual model from an external systems.

@@ -657,7 +657,7 @@ Within a workflow's steps, you resolve modules to use their service's functional

 <Note>

-Learn more about workflows in [this documentation](!docs!/learn/basics/workflows)
+Learn more about workflows in [this documentation](!docs!/learn/fundamentals/workflows)

 </Note>

@@ -743,7 +743,7 @@ You define the `syncStep` using the `createStep` function, which accepts two par

 The step function accepts the step's input as a first parameter, and an object of options as a second. The object of options has a `container` property, which is an instance of the Medusa container that you can use to resolve resources.

-In the step, you resolve from the Medusa container Sanity Module's service and [Query](!docs!/learn/advanced-development/module-links/query), which is a tool that allows you to retrieve data across modules and links.
+In the step, you resolve from the Medusa container Sanity Module's service and [Query](!docs!/learn/fundamentals/module-links/query), which is a tool that allows you to retrieve data across modules and links.

 You use Query's `graph` method to retrieve products, filtering them by their IDs and applying pagination configurations. The `graph` method accepts a `fields` property in its object parameter, which indicates the product data model's fields and relations to retrieve.

@@ -816,7 +816,7 @@ If no errors occur, the step returns an instance of `StepResponse`, which must b

 <Note title="Tip">

-Learn more about compensation functions in [this documentation](!docs!/learn/advanced-development/workflows/compensation-function).
+Learn more about compensation functions in [this documentation](!docs!/learn/fundamentals/workflows/compensation-function).

 </Note>

@@ -895,7 +895,7 @@ The `retentionTime` property indicates how long should the workflow's progress b

 <Note title="Tip">

-A workflow's constructor function has some constraints in implementation. Learn more about them in [this documentation](!docs!/learn/advanced-development/workflows/constructor-constraints).
+A workflow's constructor function has some constraints in implementation. Learn more about them in [this documentation](!docs!/learn/fundamentals/workflows/constructor-constraints).

 </Note>

@@ -915,7 +915,7 @@ Subscribers are useful when you want to perform an action that isn't an integral

 <Note>

-Learn more about events and subscribers in [this documentation](!docs!/learn/basics/events-and-subscribers). You can also find the list of emitted events in [this reference](../../../events-reference/page.mdx).
+Learn more about events and subscribers in [this documentation](!docs!/learn/fundamentals/events-and-subscribers). You can also find the list of emitted events in [this reference](../../../events-reference/page.mdx).

 </Note>

@@ -1316,7 +1316,7 @@ You can now manage the product's content in Sanity, add more fields, and customi

 There are cases where you need to trigger the syncing of products manually, such as when an error occurs or you have products from before creating this integration.

-The Medusa Admin dashboard is customizable, allowing you to either inject components, called [widgets](!docs!/learn/advanced-development/admin/widgets), into existing pages, or adding new pages, called [UI routes](!docs!/learn/advanced-development/admin/ui-routes). In these customizations, you can send requests to the Medusa application to perform custom operations.
+The Medusa Admin dashboard is customizable, allowing you to either inject components, called [widgets](!docs!/learn/fundamentals/admin/widgets), into existing pages, or adding new pages, called [UI routes](!docs!/learn/fundamentals/admin/ui-routes). In these customizations, you can send requests to the Medusa application to perform custom operations.

 In this step, you'll add a widget to the product's details page. In that page, you'll show whether a product is synced with Sanity, and allow the admin user to trigger syncing it manually.

@@ -1326,7 +1326,7 @@ Before you do that, however, you need two new API routes in your Medusa applicat

 <Note title="What is an API Route?">

-An API route is a REST API endpoint that exposes commerce features to the admin dashboard or other frontend clients. Learn more about API routes in [this documentation](!docs!/learn/basics/api-routes).
+An API route is a REST API endpoint that exposes commerce features to the admin dashboard or other frontend clients. Learn more about API routes in [this documentation](!docs!/learn/fundamentals/api-routes).

 </Note>

@@ -1395,7 +1395,7 @@ You'll test out this route in a later section.

 <Note title="Tip">

-Since the API route is added under the `/admin` prefix, only authenticated admin users can access it. Learn more about protected routes in [this documentation](!docs!/learn/advanced-development/api-routes/protected-routes).
+Since the API route is added under the `/admin` prefix, only authenticated admin users can access it. Learn more about protected routes in [this documentation](!docs!/learn/fundamentals/api-routes/protected-routes).

 </Note>

@@ -1654,7 +1654,7 @@ To render a widget that matches the rest of the admin dashboard's design, you us

 <Note>

-Learn more about widgets in [this documentation](/learn/advanced-development/admin/widgets).
+Learn more about widgets in [this documentation](/learn/fundamentals/admin/widgets).

 </Note>

@@ -1676,7 +1676,7 @@ Earlier in this guide when introducing workflows, you learned that you can track

 Medusa has a [workflow engine](../../../architectural-modules/workflow-engine/page.mdx) that manages workflow executions, roll-backs, and other functionalities under the hood.

-The workflow engine is an [architectural module](!docs!/learn/advanced-development/architecture/architectural-modules), which can be replaced with a [Redis Workflow Engine](../../../architectural-modules/workflow-engine/redis/page.mdx), or a custom one of your choice, allowing you to take ownership of your application's tooling.
+The workflow engine is an [architectural module](!docs!/learn/fundamentals/modules/architectural-modules), which can be replaced with a [Redis Workflow Engine](../../../architectural-modules/workflow-engine/redis/page.mdx), or a custom one of your choice, allowing you to take ownership of your application's tooling.

 In your customizations, you can resolve the workflow engine from the container and manage executions of a workflow, such as retrieve them and check their progress.

@@ -1921,7 +1921,7 @@ To display components that match the design of the Medusa Admin, you use compone

 <Note>

-Learn more about UI routes in [this documentation](!docs!/learn/advanced-development/admin/ui-routes).
+Learn more about UI routes in [this documentation](!docs!/learn/fundamentals/admin/ui-routes).

 </Note>