docs: improve getting started chapters (#10014)

www/apps/book/app/learn/installation/page.mdx

@@ -0,0 +1,118 @@
+import { Prerequisites } from "docs-ui"
+
+export const metadata = {
+  title: `${pageNumber} Install Medusa`,
+}
+
+# {metadata.title}
+
+In this documentation, you'll learn how to install and run a Medusa application.
+
+## Create Medusa Application
+
+<Prerequisites items={[
+  {
+    text: "Node.js v20+",
+    link: "https://nodejs.org/en/download"
+  },
+  {
+    text: "Git CLI tool",
+    link: "https://git-scm.com/downloads"
+  },
+  {
+    text: "PostgreSQL",
+    link: "https://www.postgresql.org/download/"
+  }
+]} />
+
+To create a Medusa application, use the `create-medusa-app` command:
+
+```bash
+npx create-medusa-app@latest
+```
+
+When you run the command, you'll be asked for the project's name and whether you want to install the Next.js storefront.
+
+After answering the prompts, the command installs the Medusa application in a directory with your project name, and prepares a PostgreSQL database that the application connects to.
+
+<Note>
+
+Since the Medusa server is headless, the storefront is optional to install and you can install it later by following [this guide](../storefront-development/nextjs-starter/page.mdx). If you choose to install it with the Medusa application, the storefront is installed in a separate directory named `{project-name}-storefront`.
+
+</Note>
+
+### Successful Installation Result
+
+Once the Medusa application installation finishes successfully, the Medusa application will run at `http://localhost:9000`.
+
+The Medusa Admin dashboard also runs at `http://localhost:9000/app`. The installation process opens the Medusa Admin dashboard in your default browser to create a user. You can later log in with that user.
+
+If you also installed the Next.js storefront, it'll be running at `http://localhost:8000`.
+
+### Troubleshooting Installation Errors
+
+If you ran into an error during your installation, refer to the following troubleshooting guides for help:
+
+1. [create-medusa-app troubleshooting guides](!resources!/troubleshooting/create-medusa-app-errors).
+2. [CORS errors](!resources!/troubleshooting/cors-errors).
+3. [All troubleshooting guides](!resources!/troubleshooting).
+
+If you can't find your error reported anywhere, please open a [GitHub issue](https://github.com/medusajs/medusa/issues/new/choose).
+
+<Feedback
+  question="Did you install Medusa successfully?"
+  negativeQuestion="What errors or issues did you run into?"
+  showDottedSeparator={false}
+  positiveBtn="Yes"
+  negativeBtn="No"
+/>
+
+---
+
+## Run Medusa Application in Development
+
+To run the Medusa application in development, change to your application's directory and run the following command:
+
+```bash npm2yarn
+npm run dev
+```
+
+This runs your Medusa application at `http://localhost:9000`, and the Medusa Admin dashboard `http://localhost:9000/app`.
+
+<Note title="Tip">
+
+For details on starting and configuring the Next.js storefront, refer to [this documentation](../storefront-development/nextjs-starter/page.mdx).
+
+</Note>
+
+The application will restart if you make any changes to code under the `src` directory, except for admin customizations which are hot reloaded, providing you with a seamless developer experience without having to refresh your browser to see the changes.
+
+---
+
+## Create Medusa Admin User
+
+Aside from creating an admin user in the admin dashboard, you can create a user with Medusa's CLI tool.
+
+Run the following command in your Medusa application's directory to create a new admin user:
+
+```bash
+npx medusa user -e admin@medusajs.com -p supersecret
+```
+
+Replace `admin@medusajs.com` and `supersecret` with the user's email and password respectively.
+
+You can then use the user's credentials to log into the Medusa Admin application.
+
+---
+
+## Configure Medusa Application
+
+By default, your Medusa application is equipped with the basic configuration to start your development.
+
+If you run into issues with configurations, such as CORS configurations, or need to make changes to the default configuration, refer to [this guide on all available configurations](!resources!/medusa-config).
+
+---
+
+## Next Steps
+
+In the next documentation pages, you'll start customizing your Medusa application, learn about the project's directory structure, and learn about different basic concepts.

www/apps/book/app/learn/page.mdx

@@ -1,6 +1,5 @@
 import { CheckCircleSolid, BuildingStorefront, BuildingsSolid, ComputerDesktop, FlyingBox } from "@medusajs/icons"
 import { config } from "@/config"
-import { Prerequisites } from "docs-ui"
 
 export const metadata = {
   title: `${pageNumber} Introduction - ${config.titleSuffix}`,
@@ -22,31 +21,6 @@ However, unlike other platforms, Medusa is built with customization in mind. You
 
 --- 
 
-## Get started
-
-<Prerequisites items={[
-  {
-    text: "Node.js v20+",
-    link: "https://nodejs.org/en/download"
-  },
-  {
-    text: "Git CLI tool",
-    link: "https://git-scm.com/downloads"
-  },
-  {
-    text: "PostgreSQL",
-    link: "https://www.postgresql.org/download/"
-  }
-]} />
-
-Create your first Medusa store by running the following command:
-
-```bash
-npx create-medusa-app@latest
-```
-
----
-
 ## Who should use Medusa
 
 Medusa is for businesses with unique requirements that other digital commerce platforms can't easily support. Businesses of any size can use Medusa, from small startups to large enterprises - all it takes is a developer to manage and deploy your project.

www/apps/book/components/Feedback/index.tsx

@@ -32,7 +32,7 @@ const Feedback = (props: FeedbackProps) => {
       event="survey"
       pathName={feedbackPathname}
       reportLink={reportLink}
-      question="Was this chapter helpful?"
+      question={props.question || "Was this chapter helpful?"}
       {...props}
     />
   )

www/apps/book/components/Homepage/LinksSection/index.tsx

@@ -7,7 +7,7 @@ const HomepageLinksSection = () => {
       title: "Customize Medusa Application",
       links: [
         {
-          href: "/learn",
+          href: "/learn/installation",
           text: "Create your first application",
         },
         {

www/apps/book/components/MDXComponents/index.tsx

@@ -1,9 +1,11 @@
 import type { MDXComponents as MDXComponentsType } from "mdx/types"
 import { Link, MDXComponents as UiMdxComponents } from "docs-ui"
+import Feedback from "../Feedback"
 
 const MDXComponents: MDXComponentsType = {
   ...UiMdxComponents,
   a: Link,
+  Feedback,
 }
 
 export default MDXComponents

www/apps/book/sidebar.mjs

@@ -8,6 +8,11 @@ export const sidebar = numberSidebarItems(
       type: "link",
       path: "/learn",
       title: "Introduction",
+      children: [
+        {
+          type: "link",
+          path: "/learn/installation",
+          title: "Installation",
         },
         {
           type: "link",
@@ -15,6 +20,8 @@ export const sidebar = numberSidebarItems(
           title: "Your First Customizations",
           chapterTitle: "First Customization",
         },
+      ],
+    },
     {
       type: "link",
       path: "/learn/basics",

www/apps/resources/app/deployment/admin/vercel/page.mdx

@@ -15,7 +15,7 @@ In this document, you’ll learn how to deploy the Medusa Admin to [Vercel](http
 <Prerequisites items={[
   {
     text: "Medusa application’s codebase hosted on GitHub repository.",
-    link: "!docs!"
+    link: "!docs!/learn/installation"
   },
   {
     text: "Deployed Medusa application.",

www/apps/resources/app/deployment/medusa-application/railway/page.mdx

@@ -31,7 +31,7 @@ The same Medusa project is used to deploy the server and worker modes. Learn mor
 <Prerequisites items={[
   {
     text: "Medusa application’s codebase hosted on GitHub repository.",
-    link: "!docs!"
+    link: "!docs!/learn/installation"
   },
 ]} />
 

www/apps/resources/app/page.mdx

@@ -30,7 +30,7 @@ Explore Medusa's commerce modules, SDKs, configurations, recipes, and more.
 
 <Note title="Getting started?">
 
-Follow the [Medusa v2 Docs](!docs!) to become an advanced Medusa developer.
+Follow the [Medusa Docs](!docs!/learn) to become an advanced Medusa developer.
 
 </Note>
 

www/apps/resources/app/recipes/ecommerce/page.mdx

@@ -74,4 +74,4 @@ Our documentation has step-by-step guides to deploy your Medusa application, Med
 
 Along with the extensive ecommerce features, Medusa also provides the architecture and tools to customize and add new features.
 
-To learn how to develop customziations with Medusa, refer to the [Medusa documentation](!docs!)
+To learn how to develop customziations with Medusa, refer to the [Medusa documentation](!docs!/learn)

www/apps/resources/app/troubleshooting/_sections/other/cors-errors.mdx

@@ -4,19 +4,19 @@ You might see a log in your browser console, that looks like this:
 
 ![CORS error log](https://res.cloudinary.com/dza7lstvk/image/upload/v1668003322/Medusa%20Docs/Other/jnHK115_udgf2n.png)
 
-In your `medusa-config.ts` , you should ensure that you've configured your CORS settings correctly:
+In your `medusa-config.ts`, ensure that you've configured your CORS settings correctly:
 
 ```ts title="medusa-config.ts"
 module.exports = defineConfig({
   projectConfig: {
     http: {
-      storeCors: process.env.STORE_CORS,
+      storeCors: process.env.STORE_CORS || "http://localhost:8000",
-      adminCors: process.env.ADMIN_CORS,
+      adminCors: process.env.ADMIN_CORS || "http://localhost:9000",
-      authCors: process.env.AUTH_CORS,
+      authCors: process.env.AUTH_CORS || "http://localhost:8000,http://localhost:9000",
     },
     // ...
   },
 })
 ```
 
-Learn more about these configurations in [this documentation](/references/medusa-config#http)
+Learn more about these configurations in [this documentation](/references/medusa-config#http).