docs: add versioning (#1546)

docs/content/_versions.yml

@@ -0,0 +1,6 @@
+versions:
+  - title: current
+    path: /
+    latest: true
+  - title: SDK v2
+    path: /v2

docs/content/v2/1.index.md

@@ -0,0 +1,61 @@
+---
+layout: fullscreen
+navigation.title: Overview
+---
+
+
+# Magento 2 SDK
+
+Quickly build your storefront with the Alokai SDK for Magento. Connect your Magento 2 backend to any frontend framework with type-safe SDK methods
+
+## Getting Started
+
+Quickly install, configure, and start using the Magento Integration with the Alokai SDK.
+
+::grid{:columns='3'}
+#section-1
+:card{to="/general" title="What is Alokai?" description="New here? Learn about all the different ways Alokai can help you build with performant websites." icon="ri:book-2-fill"}
+
+#section-2
+:card{to="$base/getting-started/magento" title="Local Development" description="Use our CLI to setup a local Magento instance in minutes." icon="ri:terminal-box-fill"}
+
+#section-3
+:card{to="$base/api/magento-sdk" title="GitHub" description="Our Magento 2 SDK is fully open source. Explore the full source code for yourself on GitHub." icon="mdi:github" :colored-icon="false" }
+::
+
+## Guides
+
+Learn how to use the Magento 2 SDK with our guides.
+
+::grid{:columns='3'}
+#section-1
+:card{to="/general" title="What is Alokai?" description="New here? Learn about all the different ways Alokai can help you build with performant websites." icon="ri:book-2-fill"}
+
+#section-2
+:card{to="/integrations" title="Integrations" description="Connect to the third-party services you need to run your storefront, all through one consistent pattern." icon="ri:terminal-box-fill"}
+
+#section-3
+:card{to="https://docs.storefrontui.io" title="Storefront UI" description="Implement your design system with our ready to customize UI elements - built with TailwindCSS and Vue/React." icon="IconStorefrontUi" }
+
+#section-4
+:card{to="/cloud" title="Cloud" description="Deploy with confidence with production-grade cloud hosting for your Alokai applications" icon="ri:cloud-fill"}
+
+#section-5
+:card{to="/contributing" title="Contributing" description="Contribute to Alokai, ask questions, and get support from the community." icon="ri:community-line"}
+
+#section-6
+:card{to="/enterprise" title="Enterprise" description="Ready to take your storefront next to the next level? Reach out to sales to see how we can help you." icon="ri:store-3-fill"}
+
+::
+
+
+
+
+
+## Want to see other our SDK modules?
+
+The Magento 2 module is just one of many SDK modules that allow you to integrate with the various services needed to run your application. Add payment providers, CMS integrations, search engines and more to your storefront with Alokai SDKs.
+
+
+This integration is developed and maintained by the Alokai team.
+

docs/content/v2/2.getting-started/1.quick-start.md

@@ -0,0 +1,191 @@
+# Quick start
+
+Your Alokai application has two parts:
+
+1. **Server Middleware** - an Express.js application that can connect to your various third-party services (like Magento).
+
+2. **Front-end application** - any application using JavaScript or TypeScript that can connect to the server middleware. Popular choices include [Nuxt](https://nuxt.com/) and [Next.js](https://nextjs.org/).
+
+In this section, we will explain in a step-by-step guide how to use Magento 2 integration in each part of your Alokai application.
+
+:::read-more
+Learn more about the Alokai middleware layer in our [Key concepts: Middleware](/middleware) docs.
+:::
+
+:::read-more
+Learn more about the SDK in our [Key concepts: SDK](/sdk) docs.
+:::
+
+## Prerequisites
+
+- Magento configured - if you don't have your Magento 2 configured, see our [Magento Installation](./magento.md) guide.
+- Install Node.js version >=16.0
+
+## Server Middleware
+
+The first step to setup your integration is to create and configure your server middleware layer to connect to your Magento 2 backend.
+
+For an example of a generic server middleware configuration, check out one of [our boilerplates](https://github.com/vuestorefront/integration-boilerplate/tree/main/playground/middleware).
+
+:::tip Already have the server middleware configured?
+If you have the server middleware configured, you can move directly to the [SDK preparation](./quick-start.md#configuring-the-sdk) part.
+:::
+
+1. Install the dependencies needed to create your server middleware and to create a server-to-server connection with the Magento 2 backend and the server middleware.
+
+```bash
+yarn add @vue-storefront/middleware @vue-storefront/magento-api
+
+# npm install @vue-storefront/middleware @vue-storefront/magento-api
+
+# pnpm install @vue-storefront/middleware @vue-storefront/magento-api
+```
+
+2. Create a file `middleware.config.js` with server middleware configuration.
+
+```javascript
+// middleware.config.js
+
+import { config } from "dotenv";
+
+config();
+
+const cookieNames = {
+  currencyCookieName: "vsf-currency",
+  countryCookieName: "vsf-country",
+  localeCookieName: "vsf-locale",
+  cartCookieName: "vsf-cart",
+  customerCookieName: "vsf-customer",
+  storeCookieName: "vsf-store",
+  messageCookieName: "vsf-message",
+};
+
+export const integrations = {
+  magento: {
+    location: "@vue-storefront/magento-api/server",
+    configuration: {
+      api: process.env.VSF_MAGENTO_GRAPHQL_URL,
+      cookies: {
+        ...cookieNames,
+      },
+      cookiesDefaultOpts: {
+        httpOnly: process.env.VSF_COOKIE_HTTP_ONLY || false,
+        secure: process.env.VSF_COOKIE_SECURE || false,
+        sameSite: process.env.VSF_COOKIE_SAME_SITE || "lax",
+        path: process.env.VSF_COOKIE_PATH || "/",
+      },
+      defaultStore: "default",
+      customApolloHttpLinkOptions: {
+        useGETForQueries: true,
+      },
+      magentoBaseUrl: process.env.VSF_MAGENTO_BASE_URL,
+      magentoApiEndpoint: process.env.VSF_MAGENTO_GRAPHQL_URL,
+      imageProvider: process.env.NUXT_IMAGE_PROVIDER,
+      recaptcha: {
+        isEnabled: process.env.VSF_RECAPTCHA_ENABLED === "true",
+        sitekey: process.env.VSF_RECAPTCHA_SITE_KEY,
+        secretkey: process.env.VSF_RECAPTCHA_SECRET_KEY,
+        version: process.env.VSF_RECAPTCHA_VERSION,
+        score: process.env.VSF_RECAPTCHA_MIN_SCORE,
+      },
+      customer: {
+        customer_create_account_confirm: true,
+      },
+    },
+  },
+};
+```
+
+3. Configure environment variables in your `.env` file.
+
+```
+# .env
+
+VSF_NUXT_APP_ENV=production
+VSF_NUXT_APP_PORT=3000
+VSF_NUXT_APP_HOST=0.0.0.0
+
+VSF_STORE_URL=
+API_BASE_URL=
+API_SSR_BASE_URL=
+
+VSF_MAGENTO_BASE_URL=
+VSF_MAGENTO_GRAPHQL_URL=
+
+NUXT_IMAGE_PROVIDER=ipx
+
+```
+
+4. Create a `middleware.js` file. This script is used to run the server middleware.
+
+```javascript
+// middleware.js
+
+import { createServer } from "@vue-storefront/middleware";
+import { integrations } from "./middleware.config.js";
+import cors from "cors";
+
+(async () => {
+  const app = await createServer({ integrations });
+  const host = process.argv[2] ?? "0.0.0.0";
+  const port = process.argv[3] ?? 8181;
+  const CORS_MIDDLEWARE_NAME = "corsMiddleware";
+
+  const corsMiddleware = app._router.stack.find(
+    (middleware) => middleware.name === CORS_MIDDLEWARE_NAME
+  );
+
+  corsMiddleware.handle = cors({
+    origin: [
+      "http://localhost:3000",
+      ...(process.env.MIDDLEWARE_ALLOWED_ORIGINS?.split(",") ?? []),
+    ],
+    credentials: true,
+  });
+
+  app.listen(port, host, () => {
+    console.log(`Middleware started: ${host}:${port}`);
+  });
+})();
+```
+
+5. Your middleware is ready. You can start it by running `node middleware.js`. Most likely, you'll want to setup this command as a script in your `package.json` file.
+
+```json
+{
+  // ...
+  "scripts": {
+    "start": "node middleware.js"
+  }
+  // ...
+}
+```
+
+## Configuring the SDK
+
+Now, let's configure the SDK in the frontend part of your application to communicate with the server middleware.
+
+1. Initialize the SDK. Configure `middlewareModule` with `apiUrl` that points to the Magento 2 integration in the Alokai Middleware.
+
+```ts
+import { buildModule, initSDK, middlewareModule } from "@vue-storefront/sdk";
+import { Endpoints } from "@vue-storefront/magento-api";
+
+const sdkConfig = {
+  magento: buildModule(middlewareModule<Endpoints>, {
+    apiUrl: "http://localhost:8181/magento",
+  }),
+};
+
+export const sdk = initSDK(sdkConfig);
+```
+
+2. Your SDK is ready! You can now import it in the different parts of your frontend application and call methods with `sdk.magento.<METHOD_NAME>`. To see a full list of methods offered by the Magento 2 integration, check out the [API Reference](/integrations/magento/api/magento-api).
+
+For example, we can call the `products` method to fetch products from Magento 2.
+
+```ts
+import { sdk } from "./sdk";
+const products = await sdk.magento.products({});
+// returns ProductInterface[]
+```

docs/content/v2/2.getting-started/2.magento.md

@@ -0,0 +1,121 @@
+# Magento Installation
+
+Welcome to this Magento 2 installation guide! This guide will help you install Magento 2 on your local machine using our CLI.
+
+:::tip
+We created this guide to help you get up and running quickly.
+If you already have a Magento 2 instance for development, you can skip this guide.
+:::
+
+## Prerequisites
+
+Before you start, make sure you have the following tools installed:
+
+::list{type="success"}
+- [Node.js](https://nodejs.org/en/) - Node.js installed.
+- [Docker](https://docs.docker.com/get-docker/) - We recommend using [Docker Desktop](https://www.docker.com/products/docker-desktop/).
+- [Magento Marketplace account](https://account.magento.com/customer/account/create/) - to get API credentials for your Magento instance.
+::
+## Installation using CLI
+
+::tip
+This is a beta version of the CLI. If you encounter any issues, please report them on **[GitHub](https://github.com/vuestorefront/vue-storefront/issues/new/choose)**. Thanks for helping us make the CLI better!
+::
+
+## Installation steps
+
+**Supported OS:** MacOS, Linux, Windows (using WSL2)
+If you are using Windows, please proceed with the [Manual Installation](https://docs.alokai.com/magento/installation-setup/installation.html#manual-installation) guide.
+
+**Installation using CLI** is a quick and easy way to get your project up and running. It will install Alokai and Magento 2 instance locally using Docker. It will also generate sample data for your store *(optional)*.
+
+The **CLI** will guide you through the installation process and ask you to provide the required information.
+
+::tip
+The CLI may take up to 10 minutes to complete the installation process. Please be patient.
+::
+
+::steps
+#step-1
+### Run CLI to create a new project
+
+```bash
+npx @vue-storefront/cli m2-only
+```
+
+Under the hood, the CLI uses [`markshust/docker-magento`](https://github.com/markshust/docker-magento) to install a Magento 2 instance locally using Docker.
+
+
+#step-2
+### Enter project name
+
+When prompted, enter the name of your project. This name will be used as a directory name for your project.
+
+```bash
+┌ Welcome to Vue Storefront 2 CLI! 💚
+|
+◆  🚀  Please provide a name for the Magento 2 directory
+|  magentolocal
+```
+
+::warning
+
+Avoid using special characters and spaces in the project name.
+
+::
+
+#step-3
+### Provide Magento 2 API credentials
+
+When prompted, provide your Magento 2 API credentials. You can create them by following the [Get your authentication keys](https://experienceleague.adobe.com/en/docs/commerce-operations/installation-guide/prerequisites/authentication-keys) guide.
+
+If you're logged in to your Adobe marketplace account, go to [Adobe Merchant Center - Magento 2 Access Keys](https://marketplace.magento.com/customer/accessKeys/) page, to generate the access keys.
+
+When you see following prompt, enter your public and private key information.
+
+```bash
+◆ 🔐 Please provide your Magento access keys
+|
+◆ 🔑 Magento access key:
+| <YOUR_MAGENTO_PUBLIC_KEY>
+◆ 🔒 Magento secret key
+| <YOUR_MAGENTO_PRIVATE_KEY>
+```
+
+#step-4
+### Provide Magento 2 instance URL
+
+When prompted, provide the URL of your Magento 2 instance:
+
+```bash
+◆ 🌐 Magento domain name
+| <YOUR_MAGENTO_DOMAIN_NAME>
+```
+
+This URL will be used to connect Alokai to your Magento 2 instance - by default, the URL of the local Magento instance is `magento.test`. Meaning that your Alokai application can use the `https://magento.test/graphql` endpoint to communicate with Magento 2.
+
+The CLI will start installing Magento 2 instance locally using Docker. It will take a few minutes.
+
+::tip
+
+You will be asked to provide system administrator password to allow Docker to run commands on your machine.
+
+::
+
+#step-5
+### Generate sample data (optional)
+
+When prompted, select the option to generate sample data:
+
+```bash
+◆ 🛒 Do you want to generate sample data for the store?
+| > Yes / No
+```
+
+#step-6
+### Congratulations! 🎉
+
+You have successfully installed Magento 2 instance locally. You can now access connect your Alokai application using your instance's base URL and GraphQL URL. 🚀
+
+
+::