docs: preparations for preview (#7267)

* configured base paths + added development banner

* fix typelist site url

* added navbar and sidebar badges

* configure algolia filters

* remove AI assistant

* remove unused imports

* change navbar text and badge

* lint fixes

* fix build error

* add to api reference rewrites

* fix build error

* fix build errors in user-guide

* fix feedback component

* add parent title to pagination

* added breadcrumbs component

* remove user-guide links

* resolve todos

* fix details about authentication

* change documentation title

* lint content

www/apps/book/.env.sample

@@ -14,4 +14,5 @@ ANALYZE_BUNDLE=
 NEXT_PUBLIC_AI_ASSISTANT_URL=
 NEXT_PUBLIC_AI_WEBSITE_ID=
 NEXT_PUBLIC_AI_API_ASSISTANT_RECAPTCHA_SITE_KEY=
-CLOUDINARY_CLOUD_NAME=
+CLOUDINARY_CLOUD_NAME=
+NEXT_PUBLIC_BASE_PATH=

www/apps/book/app/advanced-development/api-routes/protected-routes/page.mdx

@@ -118,36 +118,43 @@ In the route handler, you resolve the `UserService`, and then use it to retrieve
 
 ## Protect Custom API Routes
 
-To protect custom API Routes that don’t start with `/store/me` or `/admin`, apply one of the following middlewares exported by the `@medusajs/medusa` package on your routes:
-
-- `authenticate`: only authenticated admin users can access the API Route.
-- `authenticateCustomer`: customer authentication isn’t required, but if a customer is logged in, it attaches their ID to the `MedusaRequest` object's `user.customer_id`.
-- `requireCustomerAuthentication`: only authenticated customers can access the API Route.
+To protect custom API Routes that don’t start with `/store/me` or `/admin`, use the `authenticate` middleware imported from `@medusajs/medusa`.
 
 For example:
 
 export const highlights = [
   ["11", "authenticate", "Only authenticated admin users can access routes starting with `/custom/admin`"],
-  ["15", "requireCustomerAuthentication", "Only authenticated customers can access routes starting with `/custom/customers`"]
+  ["17", "authenticate", "Only authenticated customers can access routes starting with `/custom/customers`"]
 ]
 
 ```ts title="src/api/middlewares.ts" highlights={highlights}
-import {
+// TODO update import
+import { 
   authenticate,
-  requireCustomerAuthentication,
-  type MiddlewaresConfig,
-} from "@medusajs/medusa"
+} from "@medusajs/medusa/dist/utils/authenticate-middleware"
 
 export const config: MiddlewaresConfig = {
   routes: [
     {
       matcher: "/custom/admin*",
-      middlewares: [authenticate()],
+      middlewares: [
+        authenticate("admin", ["session", "bearer", "api-key"]),
+      ],
     },
     {
       matcher: "/custom/customer*",
-      middlewares: [requireCustomerAuthentication()],
+      middlewares: [
+        authenticate("store", ["session", "bearer"]),
+      ],
     },
   ],
 }
-```
+```
+
+The `authenticate` middleware function accepts three parameters:
+
+1. The scope of authentication. Use `admin` for authenticating admin users, and `store` for authenticating customers.
+2. An array of the types of authentication methods allowed. Both `admin` and `store` scopes support `session` and `bearer`. The `admin` scope also supports the `api-key` authentication method.
+3. An optional object of options having the following properties:
+    1. `allowUnauthenticated`: (default: `false`) A boolean indicating whether authentication is required. For example, you may have an API route where you want to access the logged-in customer if available, but guest customers can still access it too. In that case, enable the `allowUnauthenticated` option.
+    2. `allowUnregistered`: (default: `false`) A boolean indicating whether new users can be authenticated.

www/apps/book/app/advanced-development/data-models/soft-deletable/page.mdx

@@ -77,7 +77,7 @@ const deletedRecords = await helloModuleService
   .listMySoftDeletables({
     // ...
   }, {
-    withDeleted: true
+    withDeleted: true,
   })
 ```
 

www/apps/book/app/advanced-development/events-and-subscribers/data-payload/page.mdx

@@ -39,8 +39,6 @@ export const config: SubscriberConfig = {
 
 This logs the product ID received in the `ProductService.Events.CREATED` (`product-created`) event’s data payload to the console.
 
-{/* TODO check first if the events list is still correct */}
+## List of Events with Data Payload
 
-{/* ## List of Events with Data Payload
-
-Refer to [this reference](!resources!/events-reference) for a full list of events emitted by Medusa and their data payloads. */}
+Refer to [this reference](!resources!/events-reference) for a full list of events emitted by Medusa and their data payloads.

www/apps/book/app/advanced-development/modules/module-relationships/page.mdx

@@ -79,9 +79,9 @@ The `CustomProductData` data model has a `product_id` field to reference the pro
 
 When you add a new data model, make sure to:
 
-- Create a migration for it.
-- Add it to the second parameter of the main service's factory function.
-- Add it to the container and connection loaders.
+- [Create a migration for it.](../../../basics/data-models/page.mdx#create-a-migration)
+- [Add it to the second parameter of the main service's factory function.](../service-factory/page.mdx#abstractModuleServiceFactory-parameters)
+- Add it to the [container](../container/page.mdx) and [connection](../connection-loader/page.mdx) loaders.
 
 </Note>
 
@@ -120,8 +120,8 @@ class HelloModuleService extends ModulesSdkUtils
           {
             name: ["my_custom"],
             args: {
-              entity: MyCustom.name
-            }
+              entity: MyCustom.name,
+            },
           },
           {
             name: ["custom_product_data"],
@@ -157,23 +157,23 @@ This creates a relationship to the `Product` data model of the Product Module us
     name: "serviceName",
     type: "`string`",
     optional: false,
-    description: "The name of the module (as added in `medusa-config.js`)."
+    description: "The name of your module (as added in `medusa-config.js`)."
   },
   {
     name: "primaryKeys",
     type: "`string[]`",
     optional: false,
-    description: "The primary key field names used in the module's data models.",
+    description: "The primary key field names used in your module's data models.",
   },
   {
     name: "alias",
     type: "`object[]`",
-    description: "The alias definitions for each data model in the module. This allows other modules to reference your module's data models in relationships.",
+    description: "The alias definitions for each data model in your module. This allows other modules to reference your module's data models in relationships.",
     children: [
       {
         name: "name",
         type: "`string[]`",
-        description: "The alias names used later when fetching or referencing the data in the model."
+        description: "The alias names of a data model used later when fetching or referencing the data model."
       },
       {
         name: "args",
@@ -197,19 +197,19 @@ This creates a relationship to the `Product` data model of the Product Module us
   {
     name: "relationships",
     type: "`object[]`",
-    description: "The module's relationships to other modules.",
+    description: "Your module's relationships to other modules.",
     children: [
       {
         name: "serviceName",
         type: "`string`",
         optional: false,
-        description: "The name of the module (as added in `medusa-config.js`) that this relationship is referencing. If you’re referencing a Medusa commerce module, use the `Modules` enum imported from `@medusajs/modules-sdk`."
+        description: "The name of the module (as added in `medusa-config.js`) that this relationship is referencing. When referencing a Medusa commerce module, use the `Modules` enum imported from `@medusajs/modules-sdk`."
       },
       {
         name: "alias",
         type: "`string`",
         optional: false,
-        description: "The alias of the data model you’re referencing in the other module. You can find it in the `__joinerConfig` method of the other module."
+        description: "The alias of the data model you’re referencing in the other module. You can find it in the `__joinerConfig` method of the other module's service."
       },
       {
         name: "primaryKey",

www/apps/book/app/advanced-development/modules/options/page.mdx

@@ -70,7 +70,7 @@ class HelloModuleService extends ModulesSdkUtils
       //...
       
       this.options_ = moduleOptions || {
-        capitalize: false
+        capitalize: false,
       }
     }
   }

www/apps/book/app/advanced-development/workflows/advanced-example/page.mdx

@@ -98,14 +98,14 @@ const updateProduct = createStep(
 
           return {
             ...variant,
-            options: variantOptions
+            options: variantOptions,
           }
         }),
         options: options.map((option) => ({
           ...option,
-          values: option.values.map((value) => value.value)
+          values: option.values.map((value) => value.value),
         })),
-        type_id: type.id
+        type_id: type.id,
       }
     )
   }

www/apps/book/app/layout.tsx

@@ -4,7 +4,7 @@ import { Inter, Roboto_Mono } from "next/font/google"
 import Navbar from "@/components/Navbar"
 import Providers from "@/providers"
 import "./globals.css"
-import { TightLayout } from "docs-ui"
+import { Bannerv2, TightLayout } from "docs-ui"
 import { config } from "@/config"
 import clsx from "clsx"
 import Feedback from "@/components/Feedback"
@@ -43,6 +43,7 @@ export default function RootLayout({
       NavbarComponent={Navbar}
       sidebarProps={{
         expandItems: true,
+        banner: <Bannerv2 />,
       }}
       showPagination={true}
       bodyClassName={clsx(inter.variable, robotoMono.variable)}

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

@@ -4,23 +4,34 @@ import {
   Feedback as UiFeedback,
   FeedbackProps as UiFeedbackProps,
   formatReportLink,
+  useIsBrowser,
 } from "docs-ui"
 import { usePathname } from "next/navigation"
 import { config } from "../../config"
+import { basePathUrl } from "../../utils/base-path-url"
+import { useMemo } from "react"
 
 type FeedbackProps = Omit<UiFeedbackProps, "event" | "pathName">
 
 const Feedback = (props: FeedbackProps) => {
   const pathname = usePathname()
+  const isBrowser = useIsBrowser()
+
+  const feedbackPathname = useMemo(() => basePathUrl(pathname), [pathname])
+  const reportLink = useMemo(
+    () =>
+      formatReportLink(
+        config.titleSuffix || "",
+        isBrowser ? document.title : ""
+      ),
+    [isBrowser]
+  )
 
   return (
     <UiFeedback
       event="survey"
-      pathName={pathname}
-      reportLink={formatReportLink(
-        config.titleSuffix || "",
-        typeof document !== "undefined" ? document.title : ""
-      )}
+      pathName={feedbackPathname}
+      reportLink={reportLink}
       question="Was this chapter helpful?"
       {...props}
     />

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

@@ -4,6 +4,7 @@ import { Navbar as UiNavbar, getNavbarItems } from "docs-ui"
 import { useSidebar } from "docs-ui"
 import { useMemo } from "react"
 import { config } from "../../config"
+import { basePathUrl } from "../../utils/base-path-url"
 
 const Navbar = () => {
   const { setMobileSidebarOpen, mobileSidebarOpen } = useSidebar()
@@ -12,7 +13,8 @@ const Navbar = () => {
     () =>
       getNavbarItems({
         basePath: config.baseUrl,
-        activePath: "/",
+        activePath: basePathUrl(""),
+        version: "v2",
       }),
     []
   )
@@ -20,8 +22,8 @@ const Navbar = () => {
   return (
     <UiNavbar
       logo={{
-        light: "/images/logo-icon.png",
-        dark: "/images/logo-icon-dark.png",
+        light: basePathUrl("/images/logo-icon.png"),
+        dark: basePathUrl("/images/logo-icon-dark.png"),
       }}
       items={navbarItems}
       mobileMenuButton={{

www/apps/book/config/index.ts

@@ -2,7 +2,8 @@ import { DocsConfig } from "types"
 import { sidebarConfig } from "./sidebar"
 
 export const config: DocsConfig = {
-  titleSuffix: "Medusa Book",
+  titleSuffix: "Medusa v2 Docs",
   baseUrl: process.env.NEXT_PUBLIC_BASE_URL || "http://localhost:3000",
+  basePath: process.env.NEXT_PUBLIC_BASE_PATH,
   sidebar: sidebarConfig,
 }

www/apps/book/config/sidebar.tsx

@@ -1,4 +1,4 @@
-import { Badge, mobileSidebarItems } from "docs-ui"
+import { Badge, mobileSidebarItemsV2 } from "docs-ui"
 import type { SidebarConfig, SidebarItemType } from "@/types"
 import { sidebar } from "../sidebar.mjs"
 
@@ -20,5 +20,5 @@ const normalizeSidebarItems = (items: SidebarItemType[]) =>
 export const sidebarConfig: SidebarConfig = {
   top: normalizeSidebarItems(sidebar),
   bottom: [],
-  mobile: mobileSidebarItems,
+  mobile: mobileSidebarItemsV2,
 }

www/apps/book/next.config.mjs

@@ -14,7 +14,6 @@ const withMDX = mdx({
   extension: /\.mdx?$/,
   options: {
     rehypePlugins: [
-      // TODO add V2 to path if necessary
       [
         crossProjectLinksPlugin,
         {
@@ -25,13 +24,14 @@ const withMDX = mdx({
                 process.env.VERCEL_ENV !== "production"
                   ? process.env.NEXT_PUBLIC_RESOURCES_URL
                   : undefined,
-              path: "resources",
+              path: "v2/resources",
             },
             "user-guide": {
               url:
                 process.env.VERCEL_ENV !== "production"
                   ? process.env.NEXT_PUBLIC_USER_GUIDE_URL
                   : undefined,
+              path: "v2/user-guide",
             },
             ui: {
               url:
@@ -90,31 +90,7 @@ const nextConfig = {
   pageExtensions: ["js", "jsx", "mdx", "ts", "tsx"],
 
   transpilePackages: ["docs-ui"],
-  // TODO uncomment if we decide on baes path
-  // basePath: process.env.NEXT_PUBLIC_BASE_PATH || "/v2",
-  async rewrites() {
-    return {
-      fallback: [
-        {
-          source: "/resources",
-          destination: `${process.env.NEXT_PUBLIC_RESOURCES_URL}/resources`,
-        },
-        {
-          source: "/resources/:path*",
-          destination: `${process.env.NEXT_PUBLIC_RESOURCES_URL}/resources/:path*`,
-        },
-        // TODO comment out once we have the user guide published
-        // {
-        //   source: "/user-guide",
-        //   destination: `${process.env.NEXT_PUBLIC_USER_GUIDE_URL}/user-guide`,
-        // },
-        // {
-        //   source: "/user-guide/:path*",
-        //   destination: `${process.env.NEXT_PUBLIC_USER_GUIDE_URL}/user-guide/:path*`,
-        // },
-      ],
-    }
-  },
+  basePath: process.env.NEXT_PUBLIC_BASE_PATH || "/v2",
 }
 
 export default withMDX(nextConfig)

www/apps/book/providers/search.tsx

@@ -1,11 +1,6 @@
 "use client"
 
-import {
-  SearchProvider as UiSearchProvider,
-  AiAssistantCommandIcon,
-  AiAssistantProvider,
-  searchFilters,
-} from "docs-ui"
+import { SearchProvider as UiSearchProvider, searchFiltersV2 } from "docs-ui"
 import { config } from "../config"
 
 type SearchProviderProps = {
@@ -32,15 +27,15 @@ const SearchProvider = ({ children }: SearchProviderProps) => {
             title: "Getting started? Try one of the following terms.",
             items: [
               "Install Medusa with create-medusa-app",
-              "What is a Service?",
               "What is an API route?",
+              "What is a Module?",
               "What is a Workflow?",
             ],
           },
           {
             title: "Developing with Medusa",
             items: [
-              "How to create a Service",
+              "How to create a Module",
               "How to create an API route",
               "How to create a data model",
               "How to create an admin widget",
@@ -48,32 +43,11 @@ const SearchProvider = ({ children }: SearchProviderProps) => {
           },
         ],
         checkInternalPattern: new RegExp(
-          `^${config.baseUrl}/([^(api|ui|resources)]/)*`
+          `^${config.baseUrl}/v2/([^(resources)])*`
         ),
-        filterOptions: searchFilters,
+        filterOptions: searchFiltersV2,
       }}
-      initialDefaultFilters={["docs"]}
-      commands={[
-        {
-          name: "ai-assistant",
-          icon: <AiAssistantCommandIcon />,
-          component: (
-            <AiAssistantProvider
-              apiUrl={process.env.NEXT_PUBLIC_AI_ASSISTANT_URL || "temp"}
-              websiteId={process.env.NEXT_PUBLIC_AI_WEBSITE_ID || "temp"}
-              recaptchaSiteKey={
-                process.env.NEXT_PUBLIC_AI_API_ASSISTANT_RECAPTCHA_SITE_KEY ||
-                "temp"
-              }
-            />
-          ),
-          title: "AI Assistant",
-          badge: {
-            variant: "purple",
-            children: "Beta",
-          },
-        },
-      ]}
+      initialDefaultFilters={["book"]}
     >
       {children}
     </UiSearchProvider>

www/apps/book/utils/base-path-url.ts

@@ -0,0 +1,3 @@
+export function basePathUrl(path = "") {
+  return `${process.env.NEXT_PUBLIC_BASE_PATH || ""}${path}`
+}