From c8cde862292e3394258508091d9786f57d7992b1 Mon Sep 17 00:00:00 2001
From: mkucmus <maciejkucmus@gmail.com>
Date: Wed, 10 Dec 2025 09:01:23 +0100
Subject: [PATCH 1/4] fix(docs): register missing pageRef component

---
 apps/docs/.vitepress/theme/index.ts | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/apps/docs/.vitepress/theme/index.ts b/apps/docs/.vitepress/theme/index.ts
index 27e6b9bc0..22631aa72 100644
--- a/apps/docs/.vitepress/theme/index.ts
+++ b/apps/docs/.vitepress/theme/index.ts
@@ -3,6 +3,7 @@ import { SWAGTheme } from "vitepress-shopware-docs";
 import type { App } from "vue";
 // Ai component
 // import AI from "./components/AI.vue";
+import PageRef from "./components/PageRef.vue";
 import "./custom.css";
 
 export default Object.assign(
@@ -12,6 +13,7 @@ export default Object.assign(
   {
     enhanceApp({ app }: { app: App }) {
       // app.component("AI", AI);
+      app.component("PageRef", PageRef);
       // app.provide('some-injection-key-if-needed', VALUE)
     },
   },

From 203729504dff29849546eaa5879b7d9a0c9da9c5 Mon Sep 17 00:00:00 2001
From: mkucmus <maciejkucmus@gmail.com>
Date: Wed, 10 Dec 2025 10:47:07 +0100
Subject: [PATCH 2/4] fix: changes after CR

---
 apps/docs/.vitepress/theme/index.ts | 13 +------------
 1 file changed, 1 insertion(+), 12 deletions(-)

diff --git a/apps/docs/.vitepress/theme/index.ts b/apps/docs/.vitepress/theme/index.ts
index 22631aa72..2e77ef4d5 100644
--- a/apps/docs/.vitepress/theme/index.ts
+++ b/apps/docs/.vitepress/theme/index.ts
@@ -6,15 +6,4 @@ import type { App } from "vue";
 import PageRef from "./components/PageRef.vue";
 import "./custom.css";
 
-export default Object.assign(
-  {
-    ...SWAGTheme(),
-  },
-  {
-    enhanceApp({ app }: { app: App }) {
-      // app.component("AI", AI);
-      app.component("PageRef", PageRef);
-      // app.provide('some-injection-key-if-needed', VALUE)
-    },
-  },
-);
+export default SWAGTheme();

From 792cac8abcb9c51944661eee9e6cf6349d2432cc Mon Sep 17 00:00:00 2001
From: mkucmus <maciejkucmus@gmail.com>
Date: Wed, 10 Dec 2025 10:49:05 +0100
Subject: [PATCH 3/4] chore: cleanup

---
 apps/docs/.vitepress/theme/index.ts | 5 -----
 1 file changed, 5 deletions(-)

diff --git a/apps/docs/.vitepress/theme/index.ts b/apps/docs/.vitepress/theme/index.ts
index 2e77ef4d5..26eda8a3c 100644
--- a/apps/docs/.vitepress/theme/index.ts
+++ b/apps/docs/.vitepress/theme/index.ts
@@ -1,9 +1,4 @@
 import { SWAGTheme } from "vitepress-shopware-docs";
-// import './styles/index.css'
-import type { App } from "vue";
-// Ai component
-// import AI from "./components/AI.vue";
-import PageRef from "./components/PageRef.vue";
 import "./custom.css";
 
 export default SWAGTheme();

From 7897665c45509463bec40677116e91d90b732741 Mon Sep 17 00:00:00 2001
From: mkucmus <maciejkucmus@gmail.com>
Date: Thu, 11 Dec 2025 12:55:20 +0100
Subject: [PATCH 4/4] feat: utilze withBase function of vitepress to avoid 404

---
 apps/docs/.vitepress/config.ts                |  1 +
 .../.vitepress/theme/components/PageRef.vue   | 24 +++++++++++++------
 apps/docs/package.json                        |  1 +
 .../docs/src/best-practices/error-handling.md |  2 +-
 apps/docs/src/best-practices/images.md        |  2 +-
 apps/docs/src/examples/index.md               |  2 +-
 apps/docs/src/framework/composables.md        |  6 ++---
 apps/docs/src/framework/internal-structure.md | 10 ++++----
 .../src/framework/shopping-experiences.md     |  2 +-
 .../getting-started/e-commerce/payments.md    |  2 +-
 .../src/getting-started/features/index.md     |  2 +-
 .../getting-started/page-elements/images.md   |  2 +-
 .../page-elements/navigation.md               |  2 +-
 apps/docs/src/getting-started/templates.md    | 10 ++++----
 .../templates/astro-template.md               |  2 +-
 .../templates/blank-template.md               |  2 +-
 .../templates/custom-vue-project.md           |  4 ++--
 .../templates/demo-store-template.md          |  2 +-
 apps/docs/src/installation.md                 |  2 +-
 apps/docs/src/why-shopware-frontends.md       |  2 +-
 20 files changed, 47 insertions(+), 35 deletions(-)

diff --git a/apps/docs/.vitepress/config.ts b/apps/docs/.vitepress/config.ts
index 3e39045ad..914998929 100644
--- a/apps/docs/.vitepress/config.ts
+++ b/apps/docs/.vitepress/config.ts
@@ -17,6 +17,7 @@ export default defineConfigWithTheme<ThemeConfigExtended>(
   sharedConfig(
     {
       extends: baseConfig.default,
+      base: process.env.VITEPRESS_BASE || "/",
       title: "Shopware Frontends",
       description: "Documentation for Shopware developers",
       srcDir: "src",
diff --git a/apps/docs/.vitepress/theme/components/PageRef.vue b/apps/docs/.vitepress/theme/components/PageRef.vue
index 821d65b64..10f06e710 100644
--- a/apps/docs/.vitepress/theme/components/PageRef.vue
+++ b/apps/docs/.vitepress/theme/components/PageRef.vue
@@ -1,6 +1,6 @@
 <template>
   <div>
-    <a :href="page" :target="target">
+    <a :href="resolvedPage" :target="target">
       <div
         class="flex gap-3 border-1px border-#eeeeee rounded-md p-4 shadow-md bg-#fdfdfd mb-6 hover:shadow-lg hover:border-#e8e8e8 dark:border-#444 dark:bg-#222 dark:hover:border-#333 dark:hover:bg-#212121"
       >
@@ -22,25 +22,35 @@
 </template>
 
 <script>
-import { ref, useAttrs } from "vue";
+import { ref, computed, useAttrs } from "vue";
+import { withBase } from "vitepress";
 
 export default {
   setup() {
     const attrs = useAttrs();
 
     const title = ref(attrs.title);
-
     const page = ref(attrs.page);
-
     const icon = ref(attrs.icon || "");
-
     const sub = ref(attrs.sub || "");
-
     const target = ref(attrs.target || "");
 
+    // Resolve page path with base URL support
+    const resolvedPage = computed(() => {
+      const pagePath = page.value;
+
+      // External URLs - return as-is
+      if (pagePath?.startsWith("http://") || pagePath?.startsWith("https://")) {
+        return pagePath;
+      }
+
+      // Use withBase for internal links to handle base path correctly
+      return withBase(pagePath || "");
+    });
+
     return {
       title,
-      page,
+      resolvedPage,
       sub,
       icon,
       target,
diff --git a/apps/docs/package.json b/apps/docs/package.json
index 526e7f8e7..a8a674a4a 100644
--- a/apps/docs/package.json
+++ b/apps/docs/package.json
@@ -7,6 +7,7 @@
   "scripts": {
     "dev": "vitepress",
     "build": "vitepress build",
+    "build:devhub": "VITEPRESS_BASE=/frontends/ vitepress build",
     "serve": "vitepress serve"
   },
   "dependencies": {
diff --git a/apps/docs/src/best-practices/error-handling.md b/apps/docs/src/best-practices/error-handling.md
index 5164050a5..ab10e0153 100644
--- a/apps/docs/src/best-practices/error-handling.md
+++ b/apps/docs/src/best-practices/error-handling.md
@@ -21,4 +21,4 @@ Deprecated. This doc is based on the old API client. Use The [new API client](..
 
 How to for error handling in different areas and different cases with examples.
 
-<PageRef page="./error-handling/api-client-error-handling.html" title="API Client" sub="Example how to handle API errors with the API Client" />
+<PageRef page="/best-practices/error-handling/api-client-error-handling.html" title="API Client" sub="Example how to handle API errors with the API Client" />
diff --git a/apps/docs/src/best-practices/images.md b/apps/docs/src/best-practices/images.md
index 1ba08dff5..399ed9183 100644
--- a/apps/docs/src/best-practices/images.md
+++ b/apps/docs/src/best-practices/images.md
@@ -133,7 +133,7 @@ When Images occupy a big amount of space on web pages, they are a common cause o
 - Never use `loading="lazy"` on `<img>` elements if they are part of what an user see first on they viewport (consider editing the attributes for CMS elements in Shopware Experiences).
 - Utilize `fetchpriority="high"` on `<img>` also tells the browser, that the asset (LCP resource is prioritized) is important and should be taken care of as fast as possible.
 
-<PageRef page="../getting-started/page-elements/images.html" title="Images as Page-Element" sub="How to display images served by API" />
+<PageRef page="/getting-started/page-elements/images.html" title="Images as Page-Element" sub="How to display images served by API" />
 
 ## Resources
 
diff --git a/apps/docs/src/examples/index.md b/apps/docs/src/examples/index.md
index f3da13760..af0330d44 100644
--- a/apps/docs/src/examples/index.md
+++ b/apps/docs/src/examples/index.md
@@ -2,4 +2,4 @@
 Our examples have moved, please follow the link below
 :::
 
-<PageRef title="Examples" sub="Examples to kickstart your project" page="../getting-started/page-elements/examples/" />
+<PageRef title="Examples" sub="Examples to kickstart your project" page="/getting-started/page-elements/examples/" />
diff --git a/apps/docs/src/framework/composables.md b/apps/docs/src/framework/composables.md
index e22698844..7e772284c 100644
--- a/apps/docs/src/framework/composables.md
+++ b/apps/docs/src/framework/composables.md
@@ -17,6 +17,6 @@ nav:
 
 The section on composables describes context composables, shared composables and how to overwrite composables.
 
-<PageRef page="./composables/context-composables.html" title="Context Composables" sub="Context composables allow for a more granular way of sharing state between components." />
-<PageRef page="./composables/shared-composables.html" title="Shared Composables" sub="Sometimes we want only one instance of a specific composable to be shared between all components." />
-<PageRef page="./composables/overwriting-composables.html" title="Overwriting Composables" sub="Replace and overwrite almost any part of the composables package in order to achieve highly customized solution." />
+<PageRef page="/framework/composables/context-composables.html" title="Context Composables" sub="Context composables allow for a more granular way of sharing state between components." />
+<PageRef page="/framework/composables/shared-composables.html" title="Shared Composables" sub="Sometimes we want only one instance of a specific composable to be shared between all components." />
+<PageRef page="/framework/composables/overwriting-composables.html" title="Overwriting Composables" sub="Replace and overwrite almost any part of the composables package in order to achieve highly customized solution." />
diff --git a/apps/docs/src/framework/internal-structure.md b/apps/docs/src/framework/internal-structure.md
index 9738b4942..d1dd1cdf8 100644
--- a/apps/docs/src/framework/internal-structure.md
+++ b/apps/docs/src/framework/internal-structure.md
@@ -33,7 +33,7 @@ This section deals with the different packages and their abstractions. It is sor
 
 The API client provides a common interface to access the Shopware API. It can be used standalone in any JavaScript project.
 
-<PageRef page="../packages/api-client.html" title="API Client Reference" sub="Package reference with all services" />
+<PageRef page="/packages/api-client.html" title="API Client Reference" sub="Package reference with all services" />
 
 ## helpers
 
@@ -43,7 +43,7 @@ The API client provides a common interface to access the Shopware API. It can be
 
 Helpers are functions that can be used for formatting, data manipulation and other stateless tasks within any JavaScript project. They are not tied to any other components.
 
-<PageRef page="../packages/helpers.html" title="Helpers Reference" sub="Package reference with all helper methods" />
+<PageRef page="/packages/helpers.html" title="Helpers Reference" sub="Package reference with all helper methods" />
 
 ## composables
 
@@ -54,7 +54,7 @@ Helpers are functions that can be used for formatting, data manipulation and oth
 
 The composables are a set of Vue.js composition functions that can be used in any Vue.js project. They provide state management, UI logic and data fetching and are the base for all guides in our [building section](../getting-started/).
 
-<PageRef page="../packages/composables.html" title="Composables Reference" sub="Package API reference with all composables" />
+<PageRef page="/packages/composables.html" title="Composables Reference" sub="Package API reference with all composables" />
 
 ## nuxt-module
 
@@ -68,7 +68,7 @@ The Nuxt 3 module allows you to set up a Nuxt 3 project with Shopware Frontends.
 
 If you want to use these packages with a different Vue.js framework, see the guide for using Shopware Frontends in a [custom project](../getting-started/templates/custom-vue-project).
 
-<PageRef page="../packages/nuxt-module.html" title="Nuxt3 Module Reference" sub="Documentation about setup and basic usage" />
+<PageRef page="/packages/nuxt-module.html" title="Nuxt3 Module Reference" sub="Documentation about setup and basic usage" />
 
 ## cms-base
 
@@ -83,7 +83,7 @@ The CMS base is a Nuxt module that provides an implementation of all CMS compone
 
 Head to our [Content Pages](../getting-started/cms/content-pages#use-the-cms-base-package) guide to learn more.
 
-<PageRef page="../packages/cms-base.html" title="CMS Base Reference" sub="Package API reference for the CMS composables" />
+<PageRef page="/packages/cms-base.html" title="CMS Base Reference" sub="Package API reference for the CMS composables" />
 
 ## Templates & Examples
 
diff --git a/apps/docs/src/framework/shopping-experiences.md b/apps/docs/src/framework/shopping-experiences.md
index bf75a8740..4e2388461 100644
--- a/apps/docs/src/framework/shopping-experiences.md
+++ b/apps/docs/src/framework/shopping-experiences.md
@@ -47,4 +47,4 @@ export default defineNuxtConfig({
 
 ## How to build Pages, Elements and Blocks?
 
-<PageRef page="../getting-started/cms/" title="BUILDGING > CMS" sub="See the buliding chapter about CMS." />
+<PageRef page="/getting-started/cms/" title="BUILDGING > CMS" sub="See the buliding chapter about CMS." />
diff --git a/apps/docs/src/getting-started/e-commerce/payments.md b/apps/docs/src/getting-started/e-commerce/payments.md
index b8fba7e2a..7bac526fb 100644
--- a/apps/docs/src/getting-started/e-commerce/payments.md
+++ b/apps/docs/src/getting-started/e-commerce/payments.md
@@ -123,7 +123,7 @@ However, if there are no plugin-specific endpoints to interact with, the `handle
 
 See what can be achieved on Express Checkout example for PayPal provider.
 
-<PageRef page="../../../resources/integrations/payments/" title="Payment Integrations" sub="See also all our Payment Integrations." />
+<PageRef page="/resources/integrations/payments/" title="Payment Integrations" sub="See also all our Payment Integrations." />
 
 ## App server integration
 
diff --git a/apps/docs/src/getting-started/features/index.md b/apps/docs/src/getting-started/features/index.md
index 2593f861d..5bb37e568 100644
--- a/apps/docs/src/getting-started/features/index.md
+++ b/apps/docs/src/getting-started/features/index.md
@@ -14,4 +14,4 @@ Collection of specific Composable Frontends Features and documentation how to us
 
 ## Shopware Extensions
 
-<PageRef page="./custom-products.html" title="Custom Products" sub="Example of integration with Custom Products extension" />
+<PageRef page="/getting-started/features/custom-products.html" title="Custom Products" sub="Example of integration with Custom Products extension" />
diff --git a/apps/docs/src/getting-started/page-elements/images.md b/apps/docs/src/getting-started/page-elements/images.md
index a28a6d212..6c5f296b5 100644
--- a/apps/docs/src/getting-started/page-elements/images.md
+++ b/apps/docs/src/getting-started/page-elements/images.md
@@ -155,4 +155,4 @@ The `src` attribute points to the main image URL (not resized) as a fallback.
 
 As long as `thumbnails` array is fulfilled, the same strategy can be applied when we work with every `media` object for each entity available in Shopware 6.
 
-<PageRef page="../../best-practices/images.html" title="Best Practices" sub="Best Practices to work with images" />
+<PageRef page="/best-practices/images.html" title="Best Practices" sub="Best Practices to work with images" />
diff --git a/apps/docs/src/getting-started/page-elements/navigation.md b/apps/docs/src/getting-started/page-elements/navigation.md
index 14b2ad9a2..9f618e2eb 100644
--- a/apps/docs/src/getting-started/page-elements/navigation.md
+++ b/apps/docs/src/getting-started/page-elements/navigation.md
@@ -72,4 +72,4 @@ There is an additional attribute `target` used, in order to open a link in anoth
 
 ## Next steps
 
-<PageRef page="../routing.html" title="Work with routing" sub="Resolve paths and fetch content dynamically" />
+<PageRef page="/getting-started/routing.html" title="Work with routing" sub="Resolve paths and fetch content dynamically" />
diff --git a/apps/docs/src/getting-started/templates.md b/apps/docs/src/getting-started/templates.md
index 43d41fd94..ecc390164 100644
--- a/apps/docs/src/getting-started/templates.md
+++ b/apps/docs/src/getting-started/templates.md
@@ -39,7 +39,7 @@ The demo store template is a **reference implementation** of an online store UI.
 
 It is based on Nuxt3 and Tailwind.css.
 
-<PageRef page="./templates/demo-store-template.html" title="Get started with the Demo Store Template" sub="A reference implementation of a store based on Vue.js" />
+<PageRef page="/getting-started/templates/demo-store-template.html" title="Get started with the Demo Store Template" sub="A reference implementation of a store based on Vue.js" />
 
 ## Blank Template
 
@@ -49,7 +49,7 @@ If you like to start from scratch, you can use the blank template. It can be han
 
 The blank template has all "non-UI" packages pre-installed, but you have to bring your own styles and components.
 
-<PageRef page="./templates/blank-template.html" title="Get started with the Blank Template" sub="A blank Nuxt.js project pre-installed with all packages" />
+<PageRef page="/getting-started/templates/blank-template.html" title="Get started with the Blank Template" sub="A blank Nuxt.js project pre-installed with all packages" />
 
 ## Custom projects
 
@@ -57,8 +57,8 @@ It is possible to integrate Shopware Frontends into an existing project. This ca
 
 As of now, **Vue.js** and **React** projects are supported.
 
-<PageRef page="./templates/custom-vue-project.html" title="Custom Vue project" sub="Integrate Shopware Frontends into an existing Vue.js project" />
-<PageRef page="./templates/custom-react-project.html" title="Custom React project" sub="Look at the Vercel Commerce Template to learn how to setup a React project" />
+<PageRef page="/getting-started/templates/custom-vue-project.html" title="Custom Vue project" sub="Integrate Shopware Frontends into an existing Vue.js project" />
+<PageRef page="/getting-started/templates/custom-react-project.html" title="Custom React project" sub="Look at the Vercel Commerce Template to learn how to setup a React project" />
 
 ## Framework supporting Vue
 
@@ -66,4 +66,4 @@ In theory, every place where the Vue instance is available, is supported by Shop
 
 The only requirement is to have a possibility to register a Vue 3 plugin, and that's what can be done in [Astro.js](https://astro.build/) as well.
 
-<PageRef page="./templates/astro-template.html" title="Astro.js project" sub="Integrate Shopware Frontends into an SSR oriented project supporting Vue.js" />
+<PageRef page="/getting-started/templates/astro-template.html" title="Astro.js project" sub="Integrate Shopware Frontends into an SSR oriented project supporting Vue.js" />
diff --git a/apps/docs/src/getting-started/templates/astro-template.md b/apps/docs/src/getting-started/templates/astro-template.md
index 6d2267aae..25069d213 100644
--- a/apps/docs/src/getting-started/templates/astro-template.md
+++ b/apps/docs/src/getting-started/templates/astro-template.md
@@ -41,4 +41,4 @@ If the customization isn't enough, visit `src/entrypoints/_shopware.ts` file and
 
 ## What next?
 
-<PageRef page="../page-elements/navigation.html" title="Build your first component" sub="Now that your astro template is set up, let's work with the main navigation." />
+<PageRef page="/getting-started/page-elements/navigation.html" title="Build your first component" sub="Now that your astro template is set up, let's work with the main navigation." />
diff --git a/apps/docs/src/getting-started/templates/blank-template.md b/apps/docs/src/getting-started/templates/blank-template.md
index bf9db1025..ad5bc3908 100644
--- a/apps/docs/src/getting-started/templates/blank-template.md
+++ b/apps/docs/src/getting-started/templates/blank-template.md
@@ -48,4 +48,4 @@ export default defineNuxtConfig({
 
 ## What next?
 
-<PageRef page="../page-elements/navigation.html" title="Build your first component" sub="Now that your blank template is set up, let's work with the main navigation." />
+<PageRef page="/getting-started/page-elements/navigation.html" title="Build your first component" sub="Now that your blank template is set up, let's work with the main navigation." />
diff --git a/apps/docs/src/getting-started/templates/custom-vue-project.md b/apps/docs/src/getting-started/templates/custom-vue-project.md
index a19d58162..6daa75aa4 100644
--- a/apps/docs/src/getting-started/templates/custom-vue-project.md
+++ b/apps/docs/src/getting-started/templates/custom-vue-project.md
@@ -36,7 +36,7 @@ pnpm add js-cookie
 For CMS components, you can add a package that contains ready-to-use components.
 You can read more about CMS pages here:
 
-<PageRef page="../cms/content-pages.html" title="Create content pages" sub="Render a content page using components" />
+<PageRef page="/getting-started/cms/content-pages.html" title="Create content pages" sub="Render a content page using components" />
 
 <!-- automd:pm-install name="@shopware/cms-base-layer" dev -->
 
@@ -286,4 +286,4 @@ For more details, please visit this [site](https://developer.shopware.com/docs/g
 
 After your setup, you can follow our building guides to get started with Shopware Frontends
 
-<PageRef page="../../getting-started/page-elements/navigation.html" title="Getting Started - Navigation" sub="Let's implement a store navigation" />
+<PageRef page="/getting-started/page-elements/navigation.html" title="Getting Started - Navigation" sub="Let's implement a store navigation" />
diff --git a/apps/docs/src/getting-started/templates/demo-store-template.md b/apps/docs/src/getting-started/templates/demo-store-template.md
index e7c900232..080192db6 100644
--- a/apps/docs/src/getting-started/templates/demo-store-template.md
+++ b/apps/docs/src/getting-started/templates/demo-store-template.md
@@ -66,7 +66,7 @@ The demo store template is a boilerplate, so it will constantly be updated, as w
 
 One exception to the rule are CMS components. CMS components are handled as a separate package `cms-base` in Shopware Frontends and can be updated automatically. However, you can still override the components from the package in your custom project.
 
-<PageRef page="./framework/shopping-experiences.html" title="Customize CMS Components" sub="Override CMS components using the cms-base package" />
+<PageRef page="/framework/shopping-experiences.html" title="Customize CMS Components" sub="Override CMS components using the cms-base package" />
 
 ## Configure
 
diff --git a/apps/docs/src/installation.md b/apps/docs/src/installation.md
index 829325a90..3c9682144 100644
--- a/apps/docs/src/installation.md
+++ b/apps/docs/src/installation.md
@@ -74,7 +74,7 @@ The demo store template is a boilerplate, so it will constantly be updated, as w
 
 One exception to the rule are CMS components. CMS components are handled as a separate package `cms-base` in Shopware Frontends and can be updated automatically. However, you can still override the components from the package in your custom project.
 
-<PageRef page="./framework/shopping-experiences.html" title="Customize CMS Components" sub="Override CMS components using the cms-base package" />
+<PageRef page="/framework/shopping-experiences.html" title="Customize CMS Components" sub="Override CMS components using the cms-base package" />
 
 ## Configure
 
diff --git a/apps/docs/src/why-shopware-frontends.md b/apps/docs/src/why-shopware-frontends.md
index fd1614717..70a975553 100644
--- a/apps/docs/src/why-shopware-frontends.md
+++ b/apps/docs/src/why-shopware-frontends.md
@@ -66,4 +66,4 @@ We recommend having profound knowledge of Vue.js or another reactive Javascript
 
 ---
 
-<PageRef page="./getting-started/templates.html" title="Getting Started" sub="Get started with Shopware Frontends" />
+<PageRef page="/getting-started/templates.html" title="Getting Started" sub="Get started with Shopware Frontends" />