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/api-reference/.env.sample

@@ -15,4 +15,5 @@ ANALYZE_BUNDLE=
 NEXT_PUBLIC_AI_ASSISTANT_URL=
 NEXT_PUBLIC_AI_WEBSITE_ID=
 NEXT_PUBLIC_AI_API_ASSISTANT_RECAPTCHA_SITE_KEY=
-NEXT_PUBLIC_VERSIONING=
+NEXT_PUBLIC_VERSIONING=
+NEXT_PUBLIC_SHOW_V2=

www/apps/api-reference/components/Navbar/index.tsx

@@ -24,6 +24,7 @@ const Navbar = () => {
       getNavbarItems({
         basePath: config.baseUrl,
         activePath: pathname,
+        version: process.env.NEXT_PUBLIC_SHOW_V2 ? "v1" : "legacy",
       }),
     [pathname]
   )

www/apps/api-reference/config/index.ts

@@ -1,5 +1,5 @@
 import { DocsConfig } from "types"
-import { mobileSidebarItems } from "docs-ui"
+import { mobileSidebarItemsV1, legacyMobileSidebarItems } from "docs-ui"
 
 export const config: DocsConfig = {
   baseUrl: process.env.NEXT_PUBLIC_BASE_URL || "http://localhost:3000",
@@ -13,6 +13,6 @@ export const config: DocsConfig = {
       },
     ],
     bottom: [],
-    mobile: mobileSidebarItems,
+    mobile: process.env.NEXT_PUBLIC_SHOW_V2 ? mobileSidebarItemsV1 : legacyMobileSidebarItems,
   },
 }

www/apps/api-reference/next.config.mjs

@@ -4,30 +4,44 @@ import bundleAnalyzer from "@next/bundle-analyzer"
 /** @type {import('next').NextConfig} */
 const nextConfig = {
   async rewrites() {
-    return {
-      fallback: [
+    const fallbacks = [
+      {
+        source: "/ui",
+        destination: `${process.env.NEXT_PUBLIC_UI_URL}/ui`,
+      },
+      {
+        source: "/ui/:path*",
+        destination: `${process.env.NEXT_PUBLIC_UI_URL}/ui/:path*`,
+      },
+      {
+        source: "/:path*",
+        destination: `${process.env.NEXT_PUBLIC_DOCS_URL}/:path*`,
+      },
+    ]
+
+    if (process.env.NEXT_PUBLIC_SHOW_V2) {
+      fallbacks.push(
         {
-          source: "/ui",
-          destination: `${process.env.NEXT_PUBLIC_UI_URL}/ui`,
+          source: "/v2/resources",
+          destination: `${process.env.NEXT_PUBLIC_DOCS_V2_URL}/v2/resources`,
         },
         {
-          source: "/ui/:path*",
-          destination: `${process.env.NEXT_PUBLIC_UI_URL}/ui/:path*`,
+          source: "/v2/resources/:path*",
+          destination: `${process.env.NEXT_PUBLIC_DOCS_V2_URL}/v2/resources/:path*`,
         },
-        // TODO uncomment for v2
-        // {
-        //   source: "/v2",
-        //   destination: `${process.env.NEXT_PUBLIC_DOCS_V2_URL}/resources`,
-        // },
-        // {
-        //   source: "/v2/:path*",
-        //   destination: `${process.env.NEXT_PUBLIC_DOCS_V2_URL}/resources/:path*`,
-        // },
         {
-          source: "/:path*",
-          destination: `${process.env.NEXT_PUBLIC_DOCS_URL}/:path*`,
+          source: "/v2",
+          destination: `${process.env.NEXT_PUBLIC_DOCS_V2_URL}/v2`,
         },
-      ],
+        {
+          source: "/v2/:path*",
+          destination: `${process.env.NEXT_PUBLIC_DOCS_V2_URL}/v2/:path*`,
+        }
+      )
+    }
+
+    return {
+      fallback: fallbacks,
     }
   },
   webpack: (config) => {

www/apps/api-reference/providers/search.tsx

@@ -5,7 +5,7 @@ import {
   SearchProvider as UiSearchProvider,
   AiAssistantCommandIcon,
   AiAssistantProvider,
-  searchFilters,
+  searchFiltersV1,
 } from "docs-ui"
 import { config } from "../config"
 
@@ -53,7 +53,7 @@ const SearchProvider = ({ children }: SearchProviderProps) => {
         checkInternalPattern: new RegExp(
           `^${config.baseUrl}/api/(admin|store)`
         ),
-        filterOptions: searchFilters,
+        filterOptions: searchFiltersV1,
       }}
       commands={[
         {

www/apps/api-reference/providers/sidebar.tsx

@@ -1,7 +1,6 @@
 "use client"
 import {
   SidebarProvider as UiSidebarProvider,
-  mobileSidebarItems,
   usePageLoading,
   useScrollController,
 } from "docs-ui"

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,16 +13,17 @@ const Navbar = () => {
     () =>
       getNavbarItems({
         basePath: config.baseUrl,
-        activePath: "/",
+        activePath: basePathUrl(""),
+        version: "v2",
       }),
     []
   )
 
   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={{