added docusaurus admonitions to docs

2022-04-28 08:28:21 +05:30
parent d162cef4c8
commit 1241fb7b2c
25 changed files with 242 additions and 60 deletions
@@ -6,7 +6,11 @@ title: "Deploying Admin on Netlify"

 This is a guide for deploying Medusa Admin on Netlify. Netlify is a platform that offers hosting and backend services for applications and static websites.

-> At this point, you should have a running instance of Medusa Admin. If not, check out [these steps](https://github.com/medusajs/admin#-setting-up-admin) or use `npx create-medusa-app` to set up your application in a matter of minutes. For the latter, see [this guide](https://docs.medusajs.com/how-to/create-medusa-app) for a small walkthrough.
+:::note
+
+At this point, you should have a running instance of Medusa Admin. If not, check out [these steps](https://github.com/medusajs/admin#-setting-up-admin) or use `npx create-medusa-app` to set up your application in a matter of minutes. For the latter, see [this guide](https://docs.medusajs.com/how-to/create-medusa-app) for a small walkthrough.
+
+:::

 ### 1. Install the Netlify CLI

@@ -62,7 +66,11 @@ git push origin main

 Within a couple of minutes, your Medusa Admin is live and running on Netlify.

-> If you experience CORS issues in your new setup, you might need to add your admin url as part of the ADMIN_CORS environment variable in your server setup.
+:::note
+
+If you experience CORS issues in your new setup, you might need to add your admin url as part of the ADMIN_CORS environment variable in your server setup.
+
+:::

 ### What's next?

@@ -2,7 +2,11 @@

 This is a guide for deploying a Medusa project on DigitalOcean App Platform.

-> It is assumed, that you are currently running a local instance of Medusa. If not, check out our [Quickstart](https://docs.medusajs.com/quickstart/quick-start) or use `npx create-medusa-app` to set up your application in a matter of minutes. For the latter, see [this guide](https://docs.medusajs.com/how-to/create-medusa-app) for a small walkthrough.
+:::note
+
+It is assumed, that you are currently running a local instance of Medusa. If not, check out our [Quickstart](https://docs.medusajs.com/quickstart/quick-start) or use `npx create-medusa-app` to set up your application in a matter of minutes. For the latter, see [this guide](https://docs.medusajs.com/how-to/create-medusa-app) for a small walkthrough.
+
+:::

 ### 1. Configure Medusa

@@ -83,7 +87,11 @@ Navigate to the top-right dropdown **Create** and select **Apps**.

 Choose **GitHub** or **GitLab** and select the repository that holds your Medusa project. Check **Autodeploy code changes**, if you want DigitalOcean to deploy on every push to your repository.

-> It's important, that DigitalOcean is pointing to the directory holding the Medusa store engine as it is only this which that will be deployed (If you followed the quickstart guide this will simply be the created project, and if you used the npx command this will be the backend folder inside of the newly created project).
+:::note
+
+It's important, that DigitalOcean is pointing to the directory holding the Medusa store engine as it is only this which that will be deployed (If you followed the quickstart guide this will simply be the created project, and if you used the npx command this will be the backend folder inside of the newly created project).
+
+:::

 ### 5. Configure environment variables

@@ -100,7 +108,11 @@ JWT_SECRET=your-jwt-secret
 COOKIE_SECRET=your-cookie-secret
 ```

-> Make sure to use actual secrets in a production environment
+:::note
+
+Make sure to use actual secrets in a production environment
+
+:::

 ### 6. Set up a Database

@@ -12,7 +12,11 @@ This is a guide for deploying a Medusa project on Heroku. Heroku is at PaaS that
  </video>
 </div>

-> We assume, that you are currently running a local instance of Medusa. If not, check out our [Quickstart](https://docs.medusajs.com/quickstart/quick-start) or use `npx create-medusa-app` to set up your application in a matter of minutes. For the latter, see [this guide](https://docs.medusajs.com/how-to/create-medusa-app) for a small walkthrough.
+:::note
+
+We assume, that you are currently running a local instance of Medusa. If not, check out our [Quickstart](https://docs.medusajs.com/quickstart/quick-start) or use `npx create-medusa-app` to set up your application in a matter of minutes. For the latter, see [this guide](https://docs.medusajs.com/how-to/create-medusa-app) for a small walkthrough.
+
+:::

 ### 1. Install the Heroku CLI

@@ -45,7 +49,11 @@ Connect to your Heroku account from your terminal:
 heroku login
 ```

-> Follow the instructions on your terminal
+:::note
+
+Follow the instructions on your terminal
+
+:::

 ### 3. Create an app on Heroku

@@ -60,7 +68,11 @@ heroku git:remote -a medusa-test-app

 Medusa requires a Postgres database and a Redis instance to work. These are added through the Heroku CLI using the following commands.

-> In this below example, we initialize the resources on free plans. This is not a valid configuration for a production environment.
+:::note
+
+In this below example, we initialize the resources on free plans. This is not a valid configuration for a production environment.
+
+:::

 #### Postgresql

@@ -76,7 +88,11 @@ You can find more informations, plans and pricing about Heroku Postgres [here](h

 Add a Redis instance to your Heroku app

-> The addon `redistogo:nano` is free, but Heroku requires you to add a payment method to proceed.
+:::note
+
+The addon `redistogo:nano` is free, but Heroku requires you to add a payment method to proceed.
+
+:::

 ```bash
 heroku addons:create redistogo:nano
@@ -94,8 +110,11 @@ heroku config:set JWT_SECRET=your-super-secret
 heroku config:set COOKIE_SECRET=your-super-secret-pt2
 heroku config:set NPM_CONFIG_PRODUCTION=false
 ```
+:::note

-> Make sure to use actual secrets in a production environment.
+Make sure to use actual secrets in a production environment.
+
+:::

 Additionally, we need to set the buildpack to Node.js

@@ -2,7 +2,11 @@

 This is a guide for deploying a Medusa project to Qovery. Qovery is a Continuous Deployment Platform, that provides you with the developer experience of Heroku on top of your cloud provider (e.g. AWS, DigitalOcean).

-> We assume, that you are currently running a local instance of Medusa. If not, check out our [Quickstart](https://docs.medusajs.com/quickstart/quick-start) or use `npx create-medusa-app` to set up your application in a matter of minutes. For the latter, see [this guide](https://docs.medusajs.com/how-to/create-medusa-app) for a small walkthrough.
+:::note
+
+We assume, that you are currently running a local instance of Medusa. If not, check out our [Quickstart](https://docs.medusajs.com/quickstart/quick-start) or use `npx create-medusa-app` to set up your application in a matter of minutes. For the latter, see [this guide](https://docs.medusajs.com/how-to/create-medusa-app) for a small walkthrough.
+
+:::

 ### 1. Qovery Console

@@ -16,7 +20,11 @@ Create a project and an environment.

 Add a new app to your Qovery environment and connect the Git repository that holds your Medusa project. In your application settings, set the port to 9000 unless something else is specified in your setup.

-> If you used our `npx` starter, your repository will most likely hold all components; storefront, admin and backend. Ensure that **Root application path** in Qovery is pointing to your Medusa project (`/backend`).
+:::note
+
+If you used our `npx` starter, your repository will most likely hold all components; storefront, admin and backend. Ensure that **Root application path** in Qovery is pointing to your Medusa project (`/backend`).
+
+:::

 ### 4. Add a database

@@ -61,10 +69,14 @@ module.exports = {
 };
 ```

-> **IMPORTANT**: We are using the Qovery community plan, that does not allow SSL connections for the database, so this is disabled.
->
-> In a production environment, you would need the following in the config:
-> `database_extra: { ssl: { rejectUnauthorized: false } }`
+:::caution IMPORTANT
+
+We are using the Qovery community plan, that does not allow SSL connections for the database, so this is disabled.
+
+In a production environment, you would need the following in the config:
+ `database_extra: { ssl: { rejectUnauthorized: false } }`
+
+:::

 #### Add some extra variables

@@ -75,7 +87,11 @@ JTW_SECRET=something_secret_jwt
 COOKIE_SECRET=something_secret_cookie
 ```

-> Make sure to use actual secrets in a production environment.
+:::note
+
+Make sure to use actual secrets in a production environment.
+
+:::

 #### Update `package.json`

@@ -4,7 +4,11 @@ title: Create a headless ecommerce store with Gatsby, Contentful & Medusa

 # Creating a headless ecommerce store with Gatsby, Contentful and Medusa

-> Medusa is an open source headless commerce engine that allow you to create amazing digital commerce experiences. Medusa is highly customizable, allowing you to extend the core to fit your needs.
+:::note
+
+Medusa is an open source headless commerce engine that allow you to create amazing digital commerce experiences. Medusa is highly customizable, allowing you to extend the core to fit your needs.
+
+:::

 ## Introduction

@@ -33,7 +37,11 @@ If you want to jump straight to the code for this series you can checkout:

 ## Prerequisites

-> For a full guide to how to set up your development environment for Medusa please see [the tutorial](https://docs.medusajs.com/tutorials/set-up-your-development-environment)
+:::note
+
+For a full guide to how to set up your development environment for Medusa please see [the tutorial](https://docs.medusajs.com/tutorials/set-up-your-development-environment)
+
+:::

 In order to get you started with your Gatsby, Contentful, Medusa store you must complete a couple of installations:

@@ -76,11 +76,13 @@ npm run migrate:contentful --file contentful-migrations/update-page-module-valid

 To use your new Rich Text module **Content > Page > About**, and click **Add Content > Page**. You will now make use of the new Rich Text module to add some more details about your store. You can write your own text or use the text provided below if you just want to copy/paste.

-> ### About Medusa
->
-> Medusa is an open-source headless commerce engine for fast-growing businesses. Getting started with Medusa is very easy and you will be able to start selling online with a basic setup in no time, however, the real power of Medusa starts showing up when you add custom functionality and extend your core to fit your needs.
->
-> The core Medusa package and all the official Medusa plugins ship as individual NPM packages that you install into a Node project. You store and plugins are configured in your medusa-config.js file making it very easy to manage your store as your business grows. Custom functionality doesn't have to come from plugins, you can also add project-level functionality by simply adding files in your `src/` folder. Medusa will automatically register your custom functionalities in the bootstrap phase.
+:::note About Medusa
+
+ Medusa is an open-source headless commerce engine for fast-growing businesses. Getting started with Medusa is very easy and you will be able to start selling online with a basic setup in no time, however, the real power of Medusa starts showing up when you add custom functionality and extend your core to fit your needs.
+
+ The core Medusa package and all the official Medusa plugins ship as individual NPM packages that you install into a Node project. You store and plugins are configured in your medusa-config.js file making it very easy to manage your store as your business grows. Custom functionality doesn't have to come from plugins, you can also add project-level functionality by simply adding files in your `src/` folder. Medusa will automatically register your custom functionalities in the bootstrap phase.
+
+:::

 ![](https://i.imgur.com/hqiaoFq.png)

@@ -88,7 +90,11 @@ When you have added your text you can click **Publish changes** (make sure the A

 ## Updating the storefront to support the Rich Text module

-> If you want to jump straight to the final frontend code visit [medusajs/medusa-contentful-storefront@part-2](https://github.com/medusajs/medusa-contentful-storefront/tree/part-2).
+:::note
+
+ If you want to jump straight to the final frontend code visit [medusajs/medusa-contentful-storefront@part-2](https://github.com/medusajs/medusa-contentful-storefront/tree/part-2).
+
+:::

 To display your newly created Rich Text module open up the storefront code and create a new file at `src/components/rich-text/rich-text.jsx`.

@@ -77,9 +77,12 @@ class MyService extends NotificationService {

 export default MyService;
 ```
+:::note Note

-> **Note:** a notification service must have a static property called `identifier` this is used to determine which classes are called when subscribing to different events. In this case the service identifier is `my-service` so to subscribe to notifications you must use:
-> `notificationService.subscribe([eventname], "my-service")`
+ A notification service must have a static property called `identifier` this is used to determine which classes are called when subscribing to different events. In this case the service identifier is `my-service` so to subscribe to notifications you must use:
+ `notificationService.subscribe([eventname], "my-service")`
+
+:::

 The above class is an example implementation of a NotificationService. It uses a fictional email service called `CoolEmailSender` to send emails to a customer whenever an order is placed. The `sendNotification` implementation gets the event name and fetches relevant data based on what event is being processed; in this case it retrieves an order, which is later used when requesting `CoolEmailSender` to dispatch an email. The address to send the email to is likewise fetched from the order.

@@ -4,8 +4,12 @@ title: Setting up a Next.js storefront for your Medusa project

 # Setting up a Next.js storefront for your Medusa project

-> Medusa is a headless open source commerce platform giving engineers the foundation for building unique and scalable digital commerce projects through our API-first engine.
-> Being headless, our starters serve as a good foundation for you to get coupled with a frontend in a matter of minutes.
+:::note
+
+Medusa is a headless open source commerce platform giving engineers the foundation for building unique and scalable digital commerce projects through our API-first engine.
+Being headless, our starters serve as a good foundation for you to get coupled with a frontend in a matter of minutes.
+
+:::

 This article assumes you already have the Medusa project created and ready to be linked to your Next.js starter.

@@ -46,7 +46,11 @@ Then configure your `medusa-config.js` to include the plugin alongside the requi

 The two access keys in the options are the ones created in the previous section.

-> Make sure to use an environment variable for the secret key in a live environment.
+:::note
+
+Make sure to use an environment variable for the secret key in a live environment.
+
+:::

 ### Try it out

@@ -78,7 +78,11 @@ https://[bucket].s3.[region].amazonaws.com

 The two access keys in the options are the ones created in the previous section.

-> Make sure to use an environment variable for the secret key in a live environment.
+:::note
+
+Make sure to use an environment variable for the secret key in a live environment.
+
+:::

 ### Try it out

@@ -41,7 +41,11 @@ Then configure your `medusa-config.js` to include the plugin alongside the requi

 In the above options, a `spaces_url` is included. This can be found in your Space overview. The `bucket` should point to the name you gave your Space. The `endpoint` identifies the region in which you created the Space. And finally the two keys are the ones created in the previous section.

-> Make sure to use an environment variable for the secret key in a live environment.
+:::note
+
+Make sure to use an environment variable for the secret key in a live environment.
+
+:::

 ### Try it out!