From a901ec9d2144a2327fbd46ced0eeedb50a965a81 Mon Sep 17 00:00:00 2001
From: Vanessa Tran <vanessa.m.tran@gov.ab.ca>
Date: Thu, 23 Apr 2026 14:32:18 -0600
Subject: [PATCH] chore: set up github pages per pull request

---
 .github/workflows/pr-preview.yml              | 110 ++++++++++++++++++
 apps/prs/angular/src/app/app.component.html   |  12 +-
 apps/prs/angular/src/app/app.component.ts     |   7 +-
 apps/prs/angular/src/index.html               |  13 +++
 .../routes/bugs/3273/bug3273-2.component.html |   4 +-
 .../routes/bugs/3273/bug3273-2.component.ts   |   3 +-
 .../routes/bugs/3273/bug3273.component.html   |   4 +-
 .../src/routes/bugs/3273/bug3273.component.ts |   3 +-
 apps/prs/react/index.html                     |  17 ++-
 apps/prs/react/src/app/app.tsx                |  20 ++--
 apps/prs/react/src/main.tsx                   |   2 +-
 apps/prs/react/vite.config.ts                 |   1 +
 docs/astro.config.mjs                         |   8 +-
 docs/src/components/Breadcrumbs.astro         |   9 +-
 docs/src/components/ComponentsGrid.tsx        |   5 +-
 docs/src/components/ExampleCard.astro         |   6 +-
 docs/src/components/ExampleListingCard.astro  |   3 +-
 docs/src/components/ExamplesGrid.tsx          |   5 +-
 docs/src/components/ExamplesSection.astro     |   4 +-
 docs/src/components/MobileHeader.tsx          |   5 +-
 docs/src/components/nav/ComponentsSubMenu.tsx |   9 +-
 .../src/components/nav/FoundationsSubMenu.tsx |  13 ++-
 docs/src/components/nav/GetStartedSubMenu.tsx |   9 +-
 .../components/nav/MenuSecondaryContent.tsx   |   3 +-
 docs/src/components/nav/ParentMenu.tsx        |   9 +-
 docs/src/components/search/search-utils.ts    |   7 +-
 docs/src/components/search/useSearch.ts       |   3 +-
 docs/src/layouts/BaseLayout.astro             |  16 +--
 docs/src/layouts/Layout.astro                 |   4 +-
 docs/src/lib/base-url.ts                      |   8 ++
 docs/src/lib/component-thumbnails.ts          |   4 +-
 docs/src/pages/components/[slug].astro        |   6 +-
 docs/src/pages/examples/[slug].astro          |   4 +-
 docs/src/pages/examples/all.astro             |   4 +-
 docs/src/pages/examples/index.astro           |  10 +-
 .../src/pages/foundations/accessibility.astro |   5 +-
 .../content-guidelines/error-messages.astro   |   4 +-
 .../content-guidelines/helper-text.astro      |  22 ++--
 .../foundations/style-guide/colour.astro      |   4 +-
 .../foundations/style-guide/iconography.astro |   8 +-
 .../style-guide/illustrations/index.astro     |   8 +-
 .../style-guide/illustrations/scene.astro     |  31 ++---
 .../style-guide/illustrations/spot.astro      |  23 ++--
 .../foundations/style-guide/layout.astro      |  15 +--
 .../pages/foundations/style-guide/logo.astro  |  15 +--
 .../foundations/style-guide/typography.astro  |   3 +-
 .../get-started/component-lifecycle.astro     |   3 +-
 docs/src/pages/get-started/contribute.astro   |   3 +-
 docs/src/pages/get-started/designers.astro    |   5 +-
 docs/src/pages/get-started/developers.astro   |   9 +-
 .../get-started/developers/browsers.astro     |   3 +-
 .../get-started/developers/technologies.astro |   3 +-
 docs/src/pages/get-started/index.astro        |   9 +-
 .../pages/get-started/migration-guide.astro   |   3 +-
 .../pages/get-started/out-of-support.astro    |   3 +-
 docs/src/pages/index.astro                    |  21 ++--
 56 files changed, 386 insertions(+), 164 deletions(-)
 create mode 100644 .github/workflows/pr-preview.yml
 create mode 100644 docs/src/lib/base-url.ts

diff --git a/.github/workflows/pr-preview.yml b/.github/workflows/pr-preview.yml
new file mode 100644
index 0000000000..033db2b737
--- /dev/null
+++ b/.github/workflows/pr-preview.yml
@@ -0,0 +1,110 @@
+name: PR Preview (GitHub Pages)
+
+on:
+  pull_request:
+    types: [opened, reopened, synchronize, closed]
+    branches:
+      - dev
+
+concurrency:
+  group: preview-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  deploy-preview:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v5
+        with:
+          fetch-depth: 0
+
+      - uses: actions/setup-node@v6
+        with:
+          node-version: "24"
+          cache: "npm"
+          cache-dependency-path: |
+            package-lock.json
+            docs/package-lock.json
+
+      - name: Install npm 11
+        run: npm install -g npm@11
+
+      - name: Install dependencies
+        if: github.event.action != 'closed'
+        run: |
+          npm ci
+          cd docs && npm ci --legacy-peer-deps
+
+      - name: Build docs
+        if: github.event.action != 'closed'
+        env:
+          PREVIEW_SITE: https://govalta.github.io
+          PREVIEW_BASE: /ui-components/pr-preview/pr-${{ github.event.number }}/
+        run: npx nx run docs:build
+
+      - name: Build React playground
+        if: github.event.action != 'closed'
+        env:
+          PREVIEW_BASE_REACT: /ui-components/pr-preview-react/pr-${{ github.event.number }}/
+        run: npx nx run react-prs:build:production
+
+      - name: Build Angular playground
+        if: github.event.action != 'closed'
+        env:
+          PREVIEW_BASE_ANGULAR: /ui-components/pr-preview-angular/pr-${{ github.event.number }}/
+        run: npx nx run angular-prs:build:production --base-href=$PREVIEW_BASE_ANGULAR
+
+      - name: Deploy docs preview
+        uses: rossjrw/pr-preview-action@v1
+        with:
+          source-dir: ./dist/docs
+          preview-branch: gh-pages
+          umbrella-dir: pr-preview
+          action: auto
+
+      - name: Deploy React playground preview
+        uses: rossjrw/pr-preview-action@v1
+        with:
+          source-dir: ./dist/apps/prs/react
+          preview-branch: gh-pages
+          umbrella-dir: pr-preview-react
+          action: auto
+
+      - name: Deploy Angular playground preview
+        uses: rossjrw/pr-preview-action@v1
+        with:
+          source-dir: ./dist/apps/prs/angular/browser
+          preview-branch: gh-pages
+          umbrella-dir: pr-preview-angular
+          action: auto
+
+      - name: Post consolidated preview comment
+        if: github.event.action != 'closed'
+        uses: marocchino/sticky-pull-request-comment@v2
+        with:
+          header: pr-preview-all
+          message: |
+            ## Preview links
+
+            | Target | URL |
+            |---|---|
+            | Docs | https://govalta.github.io/ui-components/pr-preview/pr-${{ github.event.number }}/ |
+            | React playground | https://govalta.github.io/ui-components/pr-preview-react/pr-${{ github.event.number }}/ |
+            | Angular playground | https://govalta.github.io/ui-components/pr-preview-angular/pr-${{ github.event.number }}/ |
+
+            Built from commit ${{ github.event.pull_request.head.sha }}. Previews are removed automatically when this PR closes.
+
+      - name: Post cleanup notice
+        if: github.event.action == 'closed'
+        uses: marocchino/sticky-pull-request-comment@v2
+        with:
+          header: pr-preview-all
+          message: |
+            ## Preview removed
+
+            All preview folders cleaned from gh-pages branch.
diff --git a/apps/prs/angular/src/app/app.component.html b/apps/prs/angular/src/app/app.component.html
index 3ddf65fc39..780a3016ff 100644
--- a/apps/prs/angular/src/app/app.component.html
+++ b/apps/prs/angular/src/app/app.component.html
@@ -2,7 +2,7 @@
   <div style="min-height: 100vh; display: flex; flex-direction: column">
     <section slot="header" id="top" class="width" role="header" style="flex: 0 0 auto">
       <goab-microsite-header type="alpha" version="UAT" />
-      <goab-app-header heading="Testing Playground" url="/"></goab-app-header>
+      <goab-app-header heading="Testing Playground" [url]="baseHref"></goab-app-header>
     </section>
 
     <div
@@ -11,7 +11,7 @@
     >
       <goab-work-side-menu
         heading="Testing Playground"
-        url="/"
+        [url]="baseHref"
         [open]="true"
         (onNavigate)="handleNavigate($event)"
         [primaryContent]="primaryTemplate"
@@ -21,14 +21,14 @@
       <ng-template #primaryTemplate>
         <goab-work-side-menu-item
           label="All Components"
-          url="/everything"
+          [url]="baseHref + 'everything'"
           icon="list"
         ></goab-work-side-menu-item>
         <goab-work-side-menu-group icon="alert-circle" heading="Bugs">
           @for (route of bugRouteDefinitions; track route.path) {
             <goab-work-side-menu-item
               [label]="route.id + ' - ' + route.title"
-              [url]="'/' + route.path"
+              [url]="baseHref + route.path"
             ></goab-work-side-menu-item>
           }
         </goab-work-side-menu-group>
@@ -36,7 +36,7 @@
           @for (route of docsRouteDefinitions; track route.path) {
             <goab-work-side-menu-item
               [label]="route.title"
-              [url]="'/' + route.path"
+              [url]="baseHref + route.path"
             ></goab-work-side-menu-item>
           }
         </goab-work-side-menu-group>
@@ -44,7 +44,7 @@
           @for (route of featureRouteDefinitions; track route.path) {
             <goab-work-side-menu-item
               [label]="route.id + ' - ' + route.title"
-              [url]="'/' + route.path"
+              [url]="baseHref + route.path"
             ></goab-work-side-menu-item>
           }
         </goab-work-side-menu-group>
diff --git a/apps/prs/angular/src/app/app.component.ts b/apps/prs/angular/src/app/app.component.ts
index 410381a6da..487604db6e 100644
--- a/apps/prs/angular/src/app/app.component.ts
+++ b/apps/prs/angular/src/app/app.component.ts
@@ -1,4 +1,5 @@
 import { Component, CUSTOM_ELEMENTS_SCHEMA, inject } from "@angular/core";
+import { LocationStrategy } from "@angular/common";
 import { Router, NavigationEnd, RouterOutlet } from "@angular/router";
 import { filter } from "rxjs/operators";
 import {
@@ -37,6 +38,7 @@ export class AppComponent {
   readonly bugRouteDefinitions = bugRouteDefinitions;
   readonly featureRouteDefinitions = featureRouteDefinitions;
   readonly docsRouteDefinitions = docsRouteDefinitions;
+  readonly baseHref = inject(LocationStrategy).getBaseHref();
 
   private fullPageRoutes = ["/features/2885"];
   private router = inject(Router);
@@ -52,6 +54,9 @@ export class AppComponent {
   }
 
   handleNavigate(path: string): void {
-    this.router.navigateByUrl(path);
+    const internal = path.startsWith(this.baseHref)
+      ? "/" + path.slice(this.baseHref.length)
+      : path;
+    this.router.navigateByUrl(internal);
   }
 }
diff --git a/apps/prs/angular/src/index.html b/apps/prs/angular/src/index.html
index 333da64741..ac2171d421 100644
--- a/apps/prs/angular/src/index.html
+++ b/apps/prs/angular/src/index.html
@@ -6,6 +6,19 @@
   <title>Angular Playground</title>
   <base href="/" />
   <meta name="viewport" content="width=device-width, initial-scale=1" />
+  <!-- spa-github-pages: restore deep-link URL after 404.html redirect -->
+  <script type="text/javascript">
+    (function (l) {
+      if (l.search[1] === "/") {
+        var decoded = l.search
+          .slice(1)
+          .split("&")
+          .map(function (s) { return s.replace(/~and~/g, "&"); })
+          .join("?");
+        window.history.replaceState(null, null, l.pathname.slice(0, -1) + decoded + l.hash);
+      }
+    })(window.location);
+  </script>
   <link rel="icon" type="image/x-icon" href="favicon.ico" />
   <script type="module" src="https://cdn.jsdelivr.net/npm/ionicons@latest/dist/ionicons/ionicons.esm.js"></script>
   <script nomodule src="https://cdn.jsdelivr.net/npm/ionicons@latest/dist/ionicons/ionicons.js"></script>
diff --git a/apps/prs/angular/src/routes/bugs/3273/bug3273-2.component.html b/apps/prs/angular/src/routes/bugs/3273/bug3273-2.component.html
index 97ee8a9528..050d133865 100644
--- a/apps/prs/angular/src/routes/bugs/3273/bug3273-2.component.html
+++ b/apps/prs/angular/src/routes/bugs/3273/bug3273-2.component.html
@@ -14,10 +14,10 @@ <h4>Scenario two</h4>
   <div style="max-width: 300px; margin-top: 24px">
     <goab-side-menu>
       <goab-side-menu-group heading="Parent Group">
-        <a href="/bugs/3273">Parent Item</a>
+        <a routerLink="/bugs/3273">Parent Item</a>
 
         <goab-side-menu-group heading="Child Group">
-          <a href="/bugs/3273-2">Child Item</a>
+          <a routerLink="/bugs/3273-2">Child Item</a>
         </goab-side-menu-group>
       </goab-side-menu-group>
     </goab-side-menu>
diff --git a/apps/prs/angular/src/routes/bugs/3273/bug3273-2.component.ts b/apps/prs/angular/src/routes/bugs/3273/bug3273-2.component.ts
index c224d01903..faac6c5cf8 100644
--- a/apps/prs/angular/src/routes/bugs/3273/bug3273-2.component.ts
+++ b/apps/prs/angular/src/routes/bugs/3273/bug3273-2.component.ts
@@ -1,11 +1,12 @@
 import { Component } from "@angular/core";
 import { CommonModule } from "@angular/common";
+import { RouterLink } from "@angular/router";
 import { GoabSideMenu, GoabSideMenuGroup } from "@abgov/angular-components";
 
 @Component({
   standalone: true,
   selector: "abgov-bug3273-2",
   templateUrl: "./bug3273-2.component.html",
-  imports: [CommonModule, GoabSideMenu, GoabSideMenuGroup],
+  imports: [CommonModule, RouterLink, GoabSideMenu, GoabSideMenuGroup],
 })
 export class Bug32732Component {}
diff --git a/apps/prs/angular/src/routes/bugs/3273/bug3273.component.html b/apps/prs/angular/src/routes/bugs/3273/bug3273.component.html
index ec8d15d996..0ec0a13a38 100644
--- a/apps/prs/angular/src/routes/bugs/3273/bug3273.component.html
+++ b/apps/prs/angular/src/routes/bugs/3273/bug3273.component.html
@@ -16,10 +16,10 @@ <h4>Scenario one</h4>
   <div style="max-width: 300px; margin-top: 24px">
     <goab-side-menu>
       <goab-side-menu-group heading="Parent Group">
-        <a href="/bugs/3273">Parent Item</a>
+        <a routerLink="/bugs/3273">Parent Item</a>
 
         <goab-side-menu-group heading="Child Group">
-          <a href="/bugs/3273-2">Child Item</a>
+          <a routerLink="/bugs/3273-2">Child Item</a>
         </goab-side-menu-group>
       </goab-side-menu-group>
     </goab-side-menu>
diff --git a/apps/prs/angular/src/routes/bugs/3273/bug3273.component.ts b/apps/prs/angular/src/routes/bugs/3273/bug3273.component.ts
index 0b587f9dd3..42399eab24 100644
--- a/apps/prs/angular/src/routes/bugs/3273/bug3273.component.ts
+++ b/apps/prs/angular/src/routes/bugs/3273/bug3273.component.ts
@@ -1,11 +1,12 @@
 import { Component } from "@angular/core";
 import { CommonModule } from "@angular/common";
+import { RouterLink } from "@angular/router";
 import { GoabSideMenu, GoabSideMenuGroup } from "@abgov/angular-components";
 
 @Component({
   standalone: true,
   selector: "abgov-bug3273",
   templateUrl: "./bug3273.component.html",
-  imports: [CommonModule, GoabSideMenu, GoabSideMenuGroup],
+  imports: [CommonModule, RouterLink, GoabSideMenu, GoabSideMenuGroup],
 })
 export class Bug3273Component {}
diff --git a/apps/prs/react/index.html b/apps/prs/react/index.html
index d2a4aba1f8..71ff4f0bed 100644
--- a/apps/prs/react/index.html
+++ b/apps/prs/react/index.html
@@ -4,10 +4,23 @@
 <head>
   <meta charset="utf-8" />
   <title>React Playground</title>
-  <base href="/" />
+  <base href="%BASE_URL%" />
 
   <meta name="viewport" content="width=device-width, initial-scale=1" />
-  <link rel="icon" type="image/x-icon" href="/favicon.ico" />
+  <!-- spa-github-pages: restore deep-link URL after 404.html redirect -->
+  <script type="text/javascript">
+    (function (l) {
+      if (l.search[1] === "/") {
+        var decoded = l.search
+          .slice(1)
+          .split("&")
+          .map(function (s) { return s.replace(/~and~/g, "&"); })
+          .join("?");
+        window.history.replaceState(null, null, l.pathname.slice(0, -1) + decoded + l.hash);
+      }
+    })(window.location);
+  </script>
+  <link rel="icon" type="image/x-icon" href="%BASE_URL%favicon.ico" />
   <link rel="stylesheet" href="/src/styles.css" />
   <script
     type="module"
diff --git a/apps/prs/react/src/app/app.tsx b/apps/prs/react/src/app/app.tsx
index a4a54e3521..af954286b6 100644
--- a/apps/prs/react/src/app/app.tsx
+++ b/apps/prs/react/src/app/app.tsx
@@ -24,19 +24,25 @@ const appContentStyle: CSSProperties = {
 
 export function App() {
   const navigate = useNavigate();
+  const baseUrl = import.meta.env.BASE_URL;
+
+  const handleNavigate = (path: string) => {
+    const internal = path.startsWith(baseUrl) ? "/" + path.slice(baseUrl.length) : path;
+    navigate(internal);
+  };
 
   return (
     <GoabOneColumnLayout>
       <section slot="header" id="top">
         <GoabMicrositeHeader type="alpha" version="UAT" />
-        <GoabAppHeader heading="Testing Playground" url="/" />
+        <GoabAppHeader heading="Testing Playground" url={baseUrl} />
       </section>
       <div style={appContentStyle}>
         <GoabWorkSideMenu
           heading="Testing Playground"
-          url="/"
+          url={baseUrl}
           open={true}
-          onNavigate={(path: string) => navigate(path)}
+          onNavigate={handleNavigate}
           primaryContent={
             <>
               <GoabWorkSideMenuGroup icon="alert-circle" heading="Bugs">
@@ -44,7 +50,7 @@ export function App() {
                   <GoabWorkSideMenuItem
                     key={route.path}
                     label={route.id + " - " + route.title}
-                    url={`/${route.path}`}
+                    url={`${baseUrl}${route.path}`}
                   />
                 ))}
               </GoabWorkSideMenuGroup>
@@ -54,7 +60,7 @@ export function App() {
                   <GoabWorkSideMenuItem
                     key={route.path}
                     label={route.id + " - " + route.title}
-                    url={`/${route.path}`}
+                    url={`${baseUrl}${route.path}`}
                   />
                 ))}
               </GoabWorkSideMenuGroup>
@@ -63,11 +69,11 @@ export function App() {
                   <GoabWorkSideMenuItem
                     key={route.path}
                     label={route.title}
-                    url={`/${route.path}`}
+                    url={`${baseUrl}${route.path}`}
                   />
                 ))}
               </GoabWorkSideMenuGroup>
-              <GoabWorkSideMenuItem icon="list" label="Everything" url="/everything" />
+              <GoabWorkSideMenuItem icon="list" label="Everything" url={`${baseUrl}everything`} />
             </>
           }
         />
diff --git a/apps/prs/react/src/main.tsx b/apps/prs/react/src/main.tsx
index cf3f895b38..83464a9fb6 100644
--- a/apps/prs/react/src/main.tsx
+++ b/apps/prs/react/src/main.tsx
@@ -11,7 +11,7 @@ const root = ReactDOM.createRoot(document.getElementById("root") as HTMLElement)
 
 root.render(
   <StrictMode>
-    <BrowserRouter>
+    <BrowserRouter basename={import.meta.env.BASE_URL}>
       <Routes>
         <Route path="/everything/b" element={<EverythingBRoute />} />
         <Route path="/" element={<App />}>
diff --git a/apps/prs/react/vite.config.ts b/apps/prs/react/vite.config.ts
index f77894c6f3..0221a5f9b4 100644
--- a/apps/prs/react/vite.config.ts
+++ b/apps/prs/react/vite.config.ts
@@ -5,6 +5,7 @@ import { nxViteTsPaths } from "@nx/vite/plugins/nx-tsconfig-paths.plugin";
 
 export default defineConfig({
   root: __dirname,
+  base: process.env.PREVIEW_BASE_REACT || "/",
   cacheDir: "../../../node_modules/.vite/playground/react",
 
   server: {
diff --git a/docs/astro.config.mjs b/docs/astro.config.mjs
index 1a0a2ee01d..6523a7cc5a 100644
--- a/docs/astro.config.mjs
+++ b/docs/astro.config.mjs
@@ -10,7 +10,8 @@ const workspaceRoot = path.resolve(__dirname, "..");
 
 // https://astro.build/config
 export default defineConfig({
-  site: "https://design.alberta.ca",
+  site: process.env.PREVIEW_SITE || "https://design.alberta.ca",
+  base: process.env.PREVIEW_BASE || "/",
   root: ".",
   outDir: "../dist/docs",
   redirects: {
@@ -50,6 +51,11 @@ export default defineConfig({
     resolve: {
       alias: [
         // More specific aliases must come first
+        // allow to use import { withBase } from '@/lib/base-url' instead of '../../lib/base-url'
+        {
+          find: /^@\/(.*)$/,
+          replacement: path.resolve(__dirname, "src/$1"),
+        },
         {
           find: "@abgov/react-components/experimental",
           replacement: path.resolve(
diff --git a/docs/src/components/Breadcrumbs.astro b/docs/src/components/Breadcrumbs.astro
index 211a15280a..ef9fda790c 100644
--- a/docs/src/components/Breadcrumbs.astro
+++ b/docs/src/components/Breadcrumbs.astro
@@ -12,8 +12,11 @@ interface Props {
   parentGroup?: { label: string; url?: string };
 }
 
+import { BASE_URL, withBase } from '@/lib/base-url';
+
 const { parentGroup } = Astro.props;
-const pathname = Astro.url.pathname.replace(/\/$/, '');
+const basePrefix = BASE_URL.replace(/\/$/, '');
+const pathname = Astro.url.pathname.replace(basePrefix, '').replace(/\/$/, '');
 const segments = pathname.split('/').filter(Boolean);
 
 // Show on any page within a section
@@ -64,14 +67,14 @@ for (let i = 0; i < crumbCount; i++) {
   <nav class="breadcrumbs" aria-label="Breadcrumb">
     <ol>
       <li>
-        <a href="/">Design System</a>
+        <a href={withBase("/")}>Design System</a>
         <span class="separator" aria-hidden="true">/</span>
       </li>
       {crumbs.map((crumb, i) => (
         <li>
           {/* TODO: Swap to <goa-link> once underline control lands (#3504) */}
           {crumb.hasPage ? (
-            <a href={crumb.url}>{crumb.label}</a>
+            <a href={withBase(crumb.url)}>{crumb.label}</a>
           ) : (
             <span>{crumb.label}</span>
           )}
diff --git a/docs/src/components/ComponentsGrid.tsx b/docs/src/components/ComponentsGrid.tsx
index 57c95e9455..cdf07f2a7b 100644
--- a/docs/src/components/ComponentsGrid.tsx
+++ b/docs/src/components/ComponentsGrid.tsx
@@ -12,6 +12,7 @@
 
 import React, { useState, useMemo, useCallback, useEffect, useRef } from "react";
 import { getThumbnailPath } from "../lib/component-thumbnails";
+import { withBase } from "@/lib/base-url";
 import { createPortal } from "react-dom";
 import {
   GoabButton,
@@ -532,7 +533,7 @@ export function ComponentsGrid({ components }: ComponentsGridProps) {
     (component: Component) => (
       <a
         key={component.slug}
-        href={`/components/${component.slug}`}
+        href={withBase(`/components/${component.slug}`)}
         className="component-card-link"
       >
         <div className="component-card-content">
@@ -586,7 +587,7 @@ export function ComponentsGrid({ components }: ComponentsGridProps) {
     (component: Component) => (
       <tr key={component.slug}>
         <td>
-          <a href={`/components/${component.slug}`} className="component-table-link">
+          <a href={withBase(`/components/${component.slug}`)} className="component-table-link">
             {component.data.name}
           </a>
         </td>
diff --git a/docs/src/components/ExampleCard.astro b/docs/src/components/ExampleCard.astro
index 31bb5dc0cb..552942b43c 100644
--- a/docs/src/components/ExampleCard.astro
+++ b/docs/src/components/ExampleCard.astro
@@ -27,6 +27,8 @@ const scaleColors: Record<string, { bg: string; color: string }> = {
 };
 
 const scaleStyle = scaleColors[data.scale] || { bg: '#f5f5f5', color: '#666' };
+
+import { withBase } from '@/lib/base-url';
 ---
 
 <article class="example-card">
@@ -66,7 +68,7 @@ const scaleStyle = scaleColors[data.scale] || { bg: '#f5f5f5', color: '#666' };
       <strong>Components:</strong>
       {data.components.map((comp, i) => (
         <>
-          <a href={`/components/${comp}`} class="component-link">{comp}</a>
+          <a href={withBase(`/components/${comp}`)} class="component-link">{comp}</a>
           {i < data.components.length - 1 && ', '}
         </>
       ))}
@@ -87,7 +89,7 @@ const scaleStyle = scaleColors[data.scale] || { bg: '#f5f5f5', color: '#666' };
         <strong>Related:</strong>
         {data.relatedExamples.map((rel, i) => (
           <>
-            <a href={`/examples/${rel}`}>{rel}</a>
+            <a href={withBase(`/examples/${rel}`)}>{rel}</a>
             {i < data.relatedExamples!.length - 1 && ', '}
           </>
         ))}
diff --git a/docs/src/components/ExampleListingCard.astro b/docs/src/components/ExampleListingCard.astro
index 0af66d1915..134d0d4214 100644
--- a/docs/src/components/ExampleListingCard.astro
+++ b/docs/src/components/ExampleListingCard.astro
@@ -14,7 +14,8 @@ interface Props {
 const { example } = Astro.props;
 const { data, slug } = example;
 
-const href = `/examples/${slug}`;
+import { withBase } from '@/lib/base-url';
+const href = withBase(`/examples/${slug}`);
 
 // Format category for display
 function formatCategory(category: string): string {
diff --git a/docs/src/components/ExamplesGrid.tsx b/docs/src/components/ExamplesGrid.tsx
index df1d01eecc..ab931cd762 100644
--- a/docs/src/components/ExamplesGrid.tsx
+++ b/docs/src/components/ExamplesGrid.tsx
@@ -13,6 +13,7 @@
 
 import React, { useState, useMemo, useCallback, useEffect, useRef } from "react";
 import { createPortal } from "react-dom";
+import { withBase } from "@/lib/base-url";
 import {
   GoabButton,
   GoabButtonGroup,
@@ -571,7 +572,7 @@ export function ExamplesGrid({ examples }: ExamplesGridProps) {
     (example: Example) => (
       <a
         key={example.slug}
-        href={`/examples/${example.slug}`}
+        href={withBase(`/examples/${example.slug}`)}
         className="example-card-link"
       >
         <div className="example-card-content">
@@ -655,7 +656,7 @@ export function ExamplesGrid({ examples }: ExamplesGridProps) {
     (example: Example) => (
       <tr key={example.slug}>
         <td>
-          <a href={`/examples/${example.slug}`} className="example-table-link">
+          <a href={withBase(`/examples/${example.slug}`)} className="example-table-link">
             {example.data.title}
           </a>
         </td>
diff --git a/docs/src/components/ExamplesSection.astro b/docs/src/components/ExamplesSection.astro
index 2c8f1c1b87..e840178b2d 100644
--- a/docs/src/components/ExamplesSection.astro
+++ b/docs/src/components/ExamplesSection.astro
@@ -18,6 +18,8 @@ const scaleToBadge: Record<string, string> = {
   flow: 'midtone',
   service: 'dark'
 };
+
+import { withBase } from '@/lib/base-url';
 ---
 
 {examples.length > 0 ? (
@@ -56,7 +58,7 @@ const scaleToBadge: Record<string, string> = {
               </goa-text>
               {example.data.components.map((comp, i) => (
                 <>
-                  <a href={`/components/${comp}`} class="component-link">{comp}</a>
+                  <a href={withBase(`/components/${comp}`)} class="component-link">{comp}</a>
                   {i < example.data.components.length - 1 && <span>,</span>}
                 </>
               ))}
diff --git a/docs/src/components/MobileHeader.tsx b/docs/src/components/MobileHeader.tsx
index fc9f724881..0eff6981e9 100644
--- a/docs/src/components/MobileHeader.tsx
+++ b/docs/src/components/MobileHeader.tsx
@@ -11,6 +11,7 @@
  */
 
 import { GoabIconButton } from '@abgov/react-components';
+import { withBase } from '@/lib/base-url';
 
 export function MobileHeader() {
   const handleMenuClick = () => {
@@ -32,9 +33,9 @@ export function MobileHeader() {
           onClick={handleMenuClick}
           ariaLabel="Open navigation menu"
         />
-        <a href="/" className="mobile-header__brand">
+        <a href={withBase('/')} className="mobile-header__brand">
           <img
-            src="/images/Logo.svg"
+            src={withBase('/images/Logo.svg')}
             alt=""
             width="28"
             height="28"
diff --git a/docs/src/components/nav/ComponentsSubMenu.tsx b/docs/src/components/nav/ComponentsSubMenu.tsx
index b7c88dda75..ef9eb535e7 100644
--- a/docs/src/components/nav/ComponentsSubMenu.tsx
+++ b/docs/src/components/nav/ComponentsSubMenu.tsx
@@ -13,6 +13,7 @@ import {
 } from "@abgov/react-components";
 import { MenuSecondaryContent } from "./MenuSecondaryContent";
 import type { NavCategory } from "../../lib/nav-categories";
+import { withBase } from "@/lib/base-url";
 
 interface ComponentsSubMenuProps {
   isOpen: boolean;
@@ -45,7 +46,7 @@ export function ComponentsSubMenu({
   const handleAllComponentsClick = (e: MouseEvent) => {
     e.preventDefault();
     e.stopPropagation();
-    window.location.href = "/components";
+    window.location.href = withBase("/components");
   };
 
   // Primary content: Back button + All Components link + component categories
@@ -60,7 +61,7 @@ export function ComponentsSubMenu({
           - On All Components page: use url so auto-matching highlights it
           - On component detail pages: wrap in div to prevent auto-matching */}
       {isAllComponentsPage ? (
-        <GoabWorkSideMenuItem label="All Components" url="/components" />
+        <GoabWorkSideMenuItem label="All Components" url={withBase("/components")} />
       ) : (
         <div onClick={handleAllComponentsClick} style={{ cursor: "pointer" }}>
           <GoabWorkSideMenuItem label="All Components" url="/__all_components__" />
@@ -93,7 +94,7 @@ export function ComponentsSubMenu({
                   <GoabWorkSideMenuItem
                     key={component.slug}
                     label={component.name}
-                    url={`/components/${component.slug}`}
+                    url={withBase(`/components/${component.slug}`)}
                     current={component.slug === currentSlug}
                   />
                 ))}
@@ -109,7 +110,7 @@ export function ComponentsSubMenu({
     <>
       <GoabWorkSideMenu
         heading="Design System | Components"
-        url="/"
+        url={withBase("/")}
         open={isOpen}
         onToggle={onToggle}
         onNavigate={(path: string) => {
diff --git a/docs/src/components/nav/FoundationsSubMenu.tsx b/docs/src/components/nav/FoundationsSubMenu.tsx
index 44e30e9f84..3b881630ce 100644
--- a/docs/src/components/nav/FoundationsSubMenu.tsx
+++ b/docs/src/components/nav/FoundationsSubMenu.tsx
@@ -12,6 +12,7 @@ import {
   GoabWorkSideMenuGroup,
 } from "@abgov/react-components";
 import { MenuSecondaryContent } from "./MenuSecondaryContent";
+import { withBase } from "@/lib/base-url";
 
 // Top-level pages (not in a group)
 const TOP_PAGES = [
@@ -103,7 +104,7 @@ export function FoundationsSubMenu({
 
       {/* Top-level pages */}
       {TOP_PAGES.map((page) => (
-        <GoabWorkSideMenuItem key={page.url} label={page.label} url={page.url} />
+        <GoabWorkSideMenuItem key={page.url} label={page.label} url={withBase(page.url)} />
       ))}
 
       {/* Grouped sections */}
@@ -130,7 +131,7 @@ export function FoundationsSubMenu({
                       <GoabWorkSideMenuItem
                         key={page.url}
                         label={page.label}
-                        url={page.url}
+                        url={withBase(page.url)}
                       />
                     ))}
                     {/* Illustration nested group (between Iconography and Photography) */}
@@ -142,7 +143,7 @@ export function FoundationsSubMenu({
                         <GoabWorkSideMenuItem
                           key={page.url}
                           label={page.label}
-                          url={page.url}
+                          url={withBase(page.url)}
                         />
                       ))}
                     </GoabWorkSideMenuGroup>
@@ -151,7 +152,7 @@ export function FoundationsSubMenu({
                       <GoabWorkSideMenuItem
                         key={page.url}
                         label={page.label}
-                        url={page.url}
+                        url={withBase(page.url)}
                       />
                     ))}
                   </>
@@ -160,7 +161,7 @@ export function FoundationsSubMenu({
                     <GoabWorkSideMenuItem
                       key={page.url}
                       label={page.label}
-                      url={page.url}
+                      url={withBase(page.url)}
                     />
                   ))
                 )}
@@ -175,7 +176,7 @@ export function FoundationsSubMenu({
   return (
     <GoabWorkSideMenu
       heading="Design System | Foundations"
-      url="/"
+      url={withBase("/")}
       open={isOpen}
       onToggle={onToggle}
       onNavigate={(path: string) => {
diff --git a/docs/src/components/nav/GetStartedSubMenu.tsx b/docs/src/components/nav/GetStartedSubMenu.tsx
index 1c18cbb4b6..abd94eccd2 100644
--- a/docs/src/components/nav/GetStartedSubMenu.tsx
+++ b/docs/src/components/nav/GetStartedSubMenu.tsx
@@ -12,6 +12,7 @@ import {
   GoabWorkSideMenuGroup,
 } from "@abgov/react-components";
 import { MenuSecondaryContent } from "./MenuSecondaryContent";
+import { withBase } from "@/lib/base-url";
 
 // Top-level pages (not in a group)
 const TOP_PAGES = [
@@ -96,7 +97,7 @@ export function GetStartedSubMenu({
 
       {/* Top-level pages */}
       {TOP_PAGES.map((page) => (
-        <GoabWorkSideMenuItem key={page.url} label={page.label} url={page.url} />
+        <GoabWorkSideMenuItem key={page.url} label={page.label} url={withBase(page.url)} />
       ))}
 
       {/* Grouped sections */}
@@ -117,7 +118,7 @@ export function GetStartedSubMenu({
                   <GoabWorkSideMenuItem
                     key={page.url}
                     label={page.label}
-                    url={page.url}
+                    url={withBase(page.url)}
                   />
                 ))}
               </GoabWorkSideMenuGroup>
@@ -128,7 +129,7 @@ export function GetStartedSubMenu({
 
       {/* Bottom pages */}
       {BOTTOM_PAGES.map((page) => (
-        <GoabWorkSideMenuItem key={page.url} label={page.label} url={page.url} />
+        <GoabWorkSideMenuItem key={page.url} label={page.label} url={withBase(page.url)} />
       ))}
     </>
   );
@@ -136,7 +137,7 @@ export function GetStartedSubMenu({
   return (
     <GoabWorkSideMenu
       heading="Design System | Get Started"
-      url="/"
+      url={withBase("/")}
       open={isOpen}
       onToggle={onToggle}
       primaryContent={primaryContent}
diff --git a/docs/src/components/nav/MenuSecondaryContent.tsx b/docs/src/components/nav/MenuSecondaryContent.tsx
index 459aa3bc28..51dd0b9808 100644
--- a/docs/src/components/nav/MenuSecondaryContent.tsx
+++ b/docs/src/components/nav/MenuSecondaryContent.tsx
@@ -10,6 +10,7 @@
 import { useCallback, useState, useEffect } from "react";
 import { GoabIcon, GoabSpacer, GoabWorkSideMenuItem } from "@abgov/react-components";
 
+import { withBase } from "@/lib/base-url";
 import "./menu-secondary.css";
 
 interface MenuSecondaryContentProps {
@@ -82,7 +83,7 @@ export function MenuSecondaryContent({ isOpen }: MenuSecondaryContentProps) {
           </>
         )}
       </button>
-      <GoabWorkSideMenuItem label="Get support" icon="help-circle" url="/support" />
+      <GoabWorkSideMenuItem label="Get support" icon="help-circle" url={withBase("/support")} />
       <GoabWorkSideMenuItem
         label="Release notes"
         icon="open"
diff --git a/docs/src/components/nav/ParentMenu.tsx b/docs/src/components/nav/ParentMenu.tsx
index a4cf282ac6..2e61b09358 100644
--- a/docs/src/components/nav/ParentMenu.tsx
+++ b/docs/src/components/nav/ParentMenu.tsx
@@ -10,6 +10,7 @@ import React from "react";
 import { GoabWorkSideMenu, GoabWorkSideMenuItem } from "@abgov/react-components";
 import type { GoabIconType } from "@abgov/ui-components-common";
 import { MenuSecondaryContent } from "./MenuSecondaryContent";
+import { withBase } from "@/lib/base-url";
 
 export type MenuSection =
   | "parent"
@@ -35,8 +36,8 @@ interface TopLevelSection {
 
 // Sections that navigate directly to a page (no submenu)
 const DIRECT_NAV_SECTIONS: Partial<Record<MenuSection, string>> = {
-  tokens: "/tokens",
-  examples: "/examples",
+  tokens: withBase("/tokens"),
+  examples: withBase("/examples"),
 };
 
 // Sections that open a submenu
@@ -90,7 +91,7 @@ export function ParentMenu({
         if (hasSubmenu) {
           // Opens submenu - use section URL when active for matching,
           // otherwise use non-matching URL to prevent false positives on homepage
-          const submenuUrl = isActive ? `/${section.id}` : "/__never_match__";
+          const submenuUrl = isActive ? withBase(`/${section.id}`) : "/__never_match__";
           return (
             <div
               key={section.id}
@@ -124,7 +125,7 @@ export function ParentMenu({
     <>
       <GoabWorkSideMenu
         heading="Design system"
-        url="/"
+        url={withBase("/")}
         open={isOpen}
         onToggle={onToggle}
         onNavigate={(path: string) => {
diff --git a/docs/src/components/search/search-utils.ts b/docs/src/components/search/search-utils.ts
index 02789d8686..bc76bc00ad 100644
--- a/docs/src/components/search/search-utils.ts
+++ b/docs/src/components/search/search-utils.ts
@@ -7,17 +7,18 @@
  */
 
 import type { SearchFilter } from "./useSearch";
+import { withBase } from "@/lib/base-url";
 
 /** Build a URL for a search result or history item by type + slug. */
 export function getResultUrl(type: string, slug: string): string {
   if (type === "page") {
-    return `/${slug}`;
+    return withBase(`/${slug}`);
   }
   if (type === "token") {
-    return `/tokens?search=${slug}`;
+    return withBase(`/tokens?search=${slug}`);
   }
   const prefix = type === "component" ? "components" : "examples";
-  return `/${prefix}/${slug}`;
+  return withBase(`/${prefix}/${slug}`);
 }
 
 /** Get the GoA icon name for a search entry type. */
diff --git a/docs/src/components/search/useSearch.ts b/docs/src/components/search/useSearch.ts
index 48063c82dd..48ddf29e3b 100644
--- a/docs/src/components/search/useSearch.ts
+++ b/docs/src/components/search/useSearch.ts
@@ -11,6 +11,7 @@
 
 import { useState, useEffect, useCallback, useRef } from "react";
 import FlexSearch from "flexsearch";
+import { withBase } from "@/lib/base-url";
 
 // ============================================================================
 // Types
@@ -244,7 +245,7 @@ async function loadSearchIndex(): Promise<SearchCache> {
 
   // Fetch and build the index
   cachePromise = (async () => {
-    const response = await fetch("/search-index.json");
+    const response = await fetch(withBase("/search-index.json"));
 
     if (!response.ok) {
       throw new Error(`Failed to load search index: ${response.status}`);
diff --git a/docs/src/layouts/BaseLayout.astro b/docs/src/layouts/BaseLayout.astro
index 63115a0394..b9f9d3fa4c 100644
--- a/docs/src/layouts/BaseLayout.astro
+++ b/docs/src/layouts/BaseLayout.astro
@@ -15,10 +15,12 @@ interface Props {
   page?: string;
 }
 
+import { withBase } from '@/lib/base-url';
+
 const { title, description, page } = Astro.props;
 const metaDescription = description || "Build on the research and experience of other service teams by using shared components, examples, tokens, and templates.";
-const ogImage = new URL('/og-image.png', Astro.site).href;
-const ogUrl = new URL(Astro.url.pathname, Astro.site).href;
+const ogImage = new URL(withBase('/og-image.png'), Astro.site).href;
+const ogUrl = new URL(withBase(Astro.url.pathname), Astro.site).href;
 ---
 
 <!DOCTYPE html>
@@ -46,11 +48,11 @@ const ogUrl = new URL(Astro.url.pathname, Astro.site).href;
   <meta name="description" content={metaDescription}>
 
   <!-- Favicon & icons -->
-  <link rel="icon" type="image/x-icon" href="/favicon.ico">
-  <link rel="icon" type="image/png" href="/favicon.png" sizes="32x32">
-  <link rel="icon" type="image/svg+xml" href="/favicon.svg" sizes="any">
-  <link rel="apple-touch-icon" href="/apple-touch-icon.png" sizes="180x180">
-  <link rel="manifest" href="/site.webmanifest">
+  <link rel="icon" type="image/x-icon" href={withBase('/favicon.ico')}>
+  <link rel="icon" type="image/png" href={withBase('/favicon.png')} sizes="32x32">
+  <link rel="icon" type="image/svg+xml" href={withBase('/favicon.svg')} sizes="any">
+  <link rel="apple-touch-icon" href={withBase('/apple-touch-icon.png')} sizes="180x180">
+  <link rel="manifest" href={withBase('/site.webmanifest')}>
   <meta name="theme-color" content="#333333">
 
   <!-- Open Graph / social sharing -->
diff --git a/docs/src/layouts/Layout.astro b/docs/src/layouts/Layout.astro
index ad19e61d44..76fa7d48ea 100644
--- a/docs/src/layouts/Layout.astro
+++ b/docs/src/layouts/Layout.astro
@@ -3,6 +3,8 @@ interface Props {
   title: string;
 }
 
+import { withBase } from '@/lib/base-url';
+
 const { title } = Astro.props;
 ---
 
@@ -17,7 +19,7 @@ const { title } = Astro.props;
     <meta charset="UTF-8" />
     <meta name="description" content="GoA UI Components Documentation" />
     <meta name="viewport" content="width=device-width" />
-    <link rel="icon" type="image/svg+xml" href="/favicon.svg" />
+    <link rel="icon" type="image/svg+xml" href={withBase('/favicon.svg')} />
     <meta name="generator" content={Astro.generator} />
     <title>{title}</title>
   </head>
diff --git a/docs/src/lib/base-url.ts b/docs/src/lib/base-url.ts
new file mode 100644
index 0000000000..1ea988dbab
--- /dev/null
+++ b/docs/src/lib/base-url.ts
@@ -0,0 +1,8 @@
+export const BASE_URL = import.meta.env.BASE_URL;
+
+export function withBase(path: string): string {
+  if (!path) return BASE_URL;
+  if (path.startsWith("http://") || path.startsWith("https://")) return path;
+  const clean = path.startsWith("/") ? path.slice(1) : path;
+  return `${BASE_URL}${clean}`;
+}
diff --git a/docs/src/lib/component-thumbnails.ts b/docs/src/lib/component-thumbnails.ts
index 4fb1e0554a..c2cb30c0e4 100644
--- a/docs/src/lib/component-thumbnails.ts
+++ b/docs/src/lib/component-thumbnails.ts
@@ -14,7 +14,9 @@ const THUMBNAIL_MAP: Record<string, string> = {
   "page-block": "block",
 };
 
+import { withBase } from "./base-url";
+
 export function getThumbnailPath(slug: string): string {
   const filename = THUMBNAIL_MAP[slug] || slug;
-  return `/images/component-thumbnails/${filename}.svg`;
+  return withBase(`/images/component-thumbnails/${filename}.svg`);
 }
diff --git a/docs/src/pages/components/[slug].astro b/docs/src/pages/components/[slug].astro
index ac75e8e581..5929614b2c 100644
--- a/docs/src/pages/components/[slug].astro
+++ b/docs/src/pages/components/[slug].astro
@@ -1,4 +1,5 @@
 ---
+import { withBase } from '@/lib/base-url';
 import { getCollection, render } from 'astro:content';
 import ComponentPageLayout from '../../layouts/ComponentPageLayout.astro';
 import Breadcrumbs from '../../components/Breadcrumbs.astro';
@@ -18,6 +19,7 @@ import {
 import { getComponentConfigurations } from '../../data/configurations';
 import { getThumbnailPath } from '../../lib/component-thumbnails';
 
+
 // Generate static paths for all components
 export async function getStaticPaths() {
   const components = await getCollection('components');
@@ -69,7 +71,7 @@ const v1DocsUrl = `https://v1.design.alberta.ca/components/${slug}`;
 >
   <div class="component-page">
   <Breadcrumbs
-    parentGroup={{ label: categoryLabel, url: `/components?category=${component.data.category}` }}
+    parentGroup={{ label: categoryLabel, url: withBase(`/components?category=${component.data.category}`) }}
   />
   <!-- Component Header -->
   <header class="component-header">
@@ -190,7 +192,7 @@ const v1DocsUrl = `https://v1.design.alberta.ca/components/${slug}`;
         {relatedComponents.map((comp) => {
           const compSlug = comp.data.slug || comp.slug;
           return (
-            <a href={`/components/${compSlug}`} class="related-card">
+            <a href={withBase(`/components/${compSlug}`)} class="related-card">
               <div class="related-card-thumbnail" aria-hidden="true">
                 <img src={getThumbnailPath(compSlug)} alt="" loading="lazy"
                   onerror="this.style.display='none';this.nextElementSibling.style.display='flex'" />
diff --git a/docs/src/pages/examples/[slug].astro b/docs/src/pages/examples/[slug].astro
index 225d088450..930c953abf 100644
--- a/docs/src/pages/examples/[slug].astro
+++ b/docs/src/pages/examples/[slug].astro
@@ -1,4 +1,5 @@
 ---
+import { withBase } from '@/lib/base-url';
 /**
  * Individual Example Page
  *
@@ -15,6 +16,7 @@ import ExampleDisplay from '../../components/ExampleDisplay.astro';
 import { TableOfContents } from '../../components/TableOfContents';
 import { getExampleCode } from '../../lib/example-code';
 
+
 // Generate static paths for all examples
 export async function getStaticPaths() {
   const examples = await getCollection('examples');
@@ -133,7 +135,7 @@ const v1DocsUrl = `https://v1.design.alberta.ca/examples/${slug}`;
         <h2>Related examples</h2>
         <div class="related-grid">
           {relatedExamples.map((related) => (
-            <a href={`/examples/${related.slug}`} class="related-card">
+            <a href={withBase(`/examples/${related.slug}`)} class="related-card">
               <span class="related-title">{related.data.title}</span>
               <span class="related-category">{formatCategory(related.data.categories[0])}</span>
             </a>
diff --git a/docs/src/pages/examples/all.astro b/docs/src/pages/examples/all.astro
index 72b9b4d56a..fadf009f6d 100644
--- a/docs/src/pages/examples/all.astro
+++ b/docs/src/pages/examples/all.astro
@@ -1,4 +1,5 @@
 ---
+import { withBase } from '@/lib/base-url';
 /**
  * All Examples Page (Testing)
  *
@@ -8,6 +9,7 @@ import { getCollection } from 'astro:content';
 import BaseLayout from '../../layouts/BaseLayout.astro';
 import ExampleDisplay from '../../components/ExampleDisplay.astro';
 
+
 // Get all examples
 const allExamples = await getCollection('examples');
 
@@ -33,7 +35,7 @@ const sortedExamples = allExamples.sort((a, b) =>
               <span class="component-pages-label">Shows on:</span>
               {example.data.components.map((comp: string, i: number) => (
                 <>
-                  <a href={`/components/${comp}`}>{comp}</a>
+                  <a href={withBase(`/components/${comp}`)}>{comp}</a>
                   {i < example.data.components.length - 1 && <span>, </span>}
                 </>
               ))}
diff --git a/docs/src/pages/examples/index.astro b/docs/src/pages/examples/index.astro
index 4ceb0659c4..75692da9e2 100644
--- a/docs/src/pages/examples/index.astro
+++ b/docs/src/pages/examples/index.astro
@@ -1,4 +1,5 @@
 ---
+import { withBase } from '@/lib/base-url';
 /**
  * Examples Listing Page
  *
@@ -14,6 +15,7 @@ import ExamplesPageLayout from '../../layouts/ExamplesPageLayout.astro';
 import Breadcrumbs from '../../components/Breadcrumbs.astro';
 import { ExamplesGrid } from '../../components/ExamplesGrid';
 
+
 // Get all examples
 const allExamples = await getCollection('examples');
 
@@ -48,15 +50,15 @@ const examples = sortedExamples.map(example => ({
     <!-- Service patterns -->
     <section class="service-patterns">
       <div class="patterns-row">
-        <a href="/examples/workspace" class="pattern-card">
-          <img src="/images/home/workspace-thumb.png" alt="" class="pattern-image" />
+        <a href={withBase(`/examples/workspace`)} class="pattern-card">
+          <img src={withBase(`/images/home/workspace-thumb.png`)} alt="" class="pattern-image" />
           <div class="pattern-text">
             <strong class="pattern-title">Workspace</strong>
             <span class="pattern-desc">For staff who review, manage, and process cases</span>
           </div>
         </a>
-        <a href="/examples/public-form" class="pattern-card">
-          <img src="/images/home/public-form-thumb.png" alt="" class="pattern-image" />
+        <a href={withBase(`/examples/public-form`)} class="pattern-card">
+          <img src={withBase(`/images/home/public-form-thumb.png`)} alt="" class="pattern-image" />
           <div class="pattern-text">
             <strong class="pattern-title">Public form</strong>
             <span class="pattern-desc">For citizens submitting applications and requests</span>
diff --git a/docs/src/pages/foundations/accessibility.astro b/docs/src/pages/foundations/accessibility.astro
index 1163380f2d..b709920c77 100644
--- a/docs/src/pages/foundations/accessibility.astro
+++ b/docs/src/pages/foundations/accessibility.astro
@@ -1,4 +1,5 @@
 ---
+import { withBase } from '@/lib/base-url';
 /**
  * Foundations - Accessibility
  *
@@ -325,8 +326,8 @@ import FoundationsSupportCallout from "../../components/FoundationsSupportCallou
     </ul>
   </goa-text>
   <goa-text size="body-m" mt="none" mb="m">
-    See the <a href="/components/callout">Callout</a> and
-    <a href="/components/notification">Notification</a> components for examples of how updates
+    See the <a href={withBase(`/components/callout`)}>Callout</a> and
+    <a href={withBase(`/components/notification`)}>Notification</a> components for examples of how updates
     are handled for assistive technology.
   </goa-text>
 
diff --git a/docs/src/pages/foundations/content-guidelines/error-messages.astro b/docs/src/pages/foundations/content-guidelines/error-messages.astro
index 445d68d2b3..d9a2e26e76 100644
--- a/docs/src/pages/foundations/content-guidelines/error-messages.astro
+++ b/docs/src/pages/foundations/content-guidelines/error-messages.astro
@@ -1,4 +1,5 @@
 ---
+import { withBase } from '@/lib/base-url';
 /**
  * Foundations - Content guidelines - Error messages
  *
@@ -11,6 +12,7 @@ import FoundationsSupportCallout from "../../../components/FoundationsSupportCal
 import DoDont from "../../../components/DoDont.astro";
 import Preview from "../../../components/Preview.astro";
 
+
 interface PatternGroup {
   id: string;
   title: string;
@@ -328,7 +330,7 @@ const formatPatterns: PatternGroup[] = [
   <goa-text size="body-m" mt="none" mb="xl">
     Refer to the
     <goa-link>
-      <a href="/components/file-upload-input">File uploader</a>
+      <a href={withBase(`/components/file-upload-input`)}>File uploader</a>
     </goa-link>
     for implementation guidance.
   </goa-text>
diff --git a/docs/src/pages/foundations/content-guidelines/helper-text.astro b/docs/src/pages/foundations/content-guidelines/helper-text.astro
index 565e5ff3d8..cf0dbead45 100644
--- a/docs/src/pages/foundations/content-guidelines/helper-text.astro
+++ b/docs/src/pages/foundations/content-guidelines/helper-text.astro
@@ -1,4 +1,5 @@
 ---
+import { withBase } from '@/lib/base-url';
 /**
  * Foundations - Content guidelines - Helper text
  *
@@ -11,6 +12,7 @@ import FoundationsSupportCallout from "../../../components/FoundationsSupportCal
 import DoDont from "../../../components/DoDont.astro";
 import Preview from "../../../components/Preview.astro";
 
+
 interface HelperTextCard {
   label: string;
   helper: string;
@@ -29,23 +31,23 @@ interface HelperTextType {
 const supportedControls = [
   {
     label: "Text inputs",
-    href: "/components/text-area",
+    href: withBase(`/components/text-area`),
   },
   {
     label: "Radios",
-    href: "/components/radio-group",
+    href: withBase(`/components/radio-group`),
   },
   {
     label: "Dropdowns",
-    href: "/components/dropdown",
+    href: withBase(`/components/dropdown`),
   },
   {
     label: "Checkboxes",
-    href: "/components/checkbox",
+    href: withBase(`/components/checkbox`),
   },
   {
     label: "Buttons",
-    href: "/components/button",
+    href: withBase(`/components/button`),
   },
 ];
 
@@ -54,10 +56,10 @@ const anatomyStructure = ["Input label", "Input control", "Helper text"];
 const helperTextQualities = ["Short", "Persistent", "Directly related to the input"];
 
 const longFormAlternatives = [
-  { label: "Accordion", href: "/components/accordion" },
-  { label: "Callout", href: "/components/callout" },
-  { label: "Details", href: "/components/details" },
-  { label: "Tooltip", href: "/components/tooltip" },
+  { label: "Accordion", href: withBase(`/components/accordion`) },
+  { label: "Callout", href: withBase(`/components/callout`) },
+  { label: "Details", href: withBase(`/components/details`) },
+  { label: "Tooltip", href: withBase(`/components/tooltip`) },
 ];
 
 const languageToneGuidance = [
@@ -254,7 +256,7 @@ function buildFieldName(...parts: string[]) {
   </goa-text>
 
   <img
-    src="/images/foundations/content-guidelines/helper-text-anatomy.svg"
+    src={withBase(`/images/foundations/content-guidelines/helper-text-anatomy.svg`)}
     alt="Annotated helper text anatomy showing an input label, input control, and helper text."
   />
 
diff --git a/docs/src/pages/foundations/style-guide/colour.astro b/docs/src/pages/foundations/style-guide/colour.astro
index 05834f50af..a7f88b836a 100644
--- a/docs/src/pages/foundations/style-guide/colour.astro
+++ b/docs/src/pages/foundations/style-guide/colour.astro
@@ -1,4 +1,5 @@
 ---
+import { withBase } from '@/lib/base-url';
 /**
  * Foundations - Style guide - Colour
  *
@@ -9,6 +10,7 @@
 import DocumentationPageLayout from "../../../layouts/DocumentationPageLayout.astro";
 import FoundationsSupportCallout from "../../../components/FoundationsSupportCallout.astro";
 
+
 const brandTokens = [
   "--goa-color-brand-default",
   "--goa-color-brand-dark",
@@ -206,7 +208,7 @@ const extendedTokenGroups = [
     </ul>
   </goa-text>
   <goa-text size="body-m" mt="none" mb="xl">
-    Refer to <a href="/tokens">design tokens</a> for implementation guidance in code.
+    Refer to <a href={withBase(`/tokens`)}>design tokens</a> for implementation guidance in code.
   </goa-text>
 
   <goa-divider version="2" mt="xl" mb="xl"></goa-divider>
diff --git a/docs/src/pages/foundations/style-guide/iconography.astro b/docs/src/pages/foundations/style-guide/iconography.astro
index 4c719d7458..0eab88cf69 100644
--- a/docs/src/pages/foundations/style-guide/iconography.astro
+++ b/docs/src/pages/foundations/style-guide/iconography.astro
@@ -1,4 +1,5 @@
 ---
+import { withBase } from '@/lib/base-url';
 /**
  * Foundations - Style guide - Iconography
  *
@@ -9,6 +10,7 @@
 import DocumentationPageLayout from "../../../layouts/DocumentationPageLayout.astro";
 import FoundationsSupportCallout from "../../../components/FoundationsSupportCallout.astro";
 
+
 const extendedIcons = [
   "accessibility",
   "add-circle",
@@ -185,7 +187,7 @@ const extendedIcons = [
     </ul>
   </goa-text>
   <goa-text size="body-m" mt="none" mb="xl">
-    Refer to the <a href="/tokens">tokens page</a> to explore available icons and properties.
+    Refer to the <a href={withBase(`/tokens`)}>tokens page</a> to explore available icons and properties.
   </goa-text>
 
   <goa-divider version="2" mt="xl" mb="xl"></goa-divider>
@@ -264,7 +266,7 @@ const extendedIcons = [
     </table>
   </goa-table>
   <goa-text size="body-m" mt="m" mb="m">
-    Refer to <a href="/tokens">design tokens</a> for implementation details.
+    Refer to <a href={withBase(`/tokens`)}>design tokens</a> for implementation details.
   </goa-text>
   <goa-text size="body-m" mt="none" mb="xl">
     When icons are interactive, it&apos;s best to make them 24 x 24 CSS pixels to meet
@@ -305,7 +307,7 @@ const extendedIcons = [
     </ol>
   </goa-text>
   <goa-text size="body-m" mt="none" mb="xl">
-    Submit proposed icons through the <a href="/get-started/contribute"
+    Submit proposed icons through the <a href={withBase(`/get-started/contribute`)}
       >design system contribution process</a
     >.
   </goa-text>
diff --git a/docs/src/pages/foundations/style-guide/illustrations/index.astro b/docs/src/pages/foundations/style-guide/illustrations/index.astro
index 6ca2c2243a..b50924b3a5 100644
--- a/docs/src/pages/foundations/style-guide/illustrations/index.astro
+++ b/docs/src/pages/foundations/style-guide/illustrations/index.astro
@@ -1,4 +1,5 @@
 ---
+import { withBase } from '@/lib/base-url';
 /**
  * Foundations - Style guide - Illustration
  *
@@ -9,6 +10,7 @@
 import DocumentationPageLayout from "../../../../layouts/DocumentationPageLayout.astro";
 import FoundationsSupportCallout from "../../../../components/FoundationsSupportCallout.astro";
 
+
 const illustrationTokens = [
   "--goa-color-illustration-dawnDark-700",
   "--goa-color-illustration-dawnDark-600",
@@ -142,7 +144,7 @@ const colourApplications = [
     across the system.
   </goa-text>
   <img
-    src="/images/foundations/style-guide/illustration-1.svg"
+    src={withBase(`/images/foundations/style-guide/illustration-1.svg`)}
     alt="Example illustration"
     width="760"
     height="224"
@@ -201,7 +203,7 @@ const colourApplications = [
     </ul>
   </goa-text>
   <img
-    src="/images/foundations/style-guide/abstract-shapes.svg"
+    src={withBase(`/images/foundations/style-guide/abstract-shapes.svg`)}
     alt="Abstract shapes example"
     width="752"
     height="371"
@@ -213,7 +215,7 @@ const colourApplications = [
     composition.
   </goa-text>
   <img
-    src="/images/foundations/style-guide/the-blend.svg"
+    src={withBase(`/images/foundations/style-guide/the-blend.svg`)}
     alt="Blend example"
     width="760"
     height="381"
diff --git a/docs/src/pages/foundations/style-guide/illustrations/scene.astro b/docs/src/pages/foundations/style-guide/illustrations/scene.astro
index 47b4477c81..e3ed91c057 100644
--- a/docs/src/pages/foundations/style-guide/illustrations/scene.astro
+++ b/docs/src/pages/foundations/style-guide/illustrations/scene.astro
@@ -1,4 +1,5 @@
 ---
+import { withBase } from '@/lib/base-url';
 /**
  * Foundations - Style guide - Illustrations - Scene
  *
@@ -43,7 +44,7 @@ import Preview from "../../../../components/Preview.astro";
   <div class="hero-illustrations">
     <div class="hero-card">
       <img
-        src="/images/foundations/illustration/scene-hero-1.svg"
+        src={withBase(`/images/foundations/illustration/scene-hero-1.svg`)}
         alt="Scene illustration of a person using a phone with floating documents"
         width="359"
         height="305"
@@ -52,7 +53,7 @@ import Preview from "../../../../components/Preview.astro";
     </div>
     <div class="hero-card">
       <img
-        src="/images/foundations/illustration/scene-hero-2.svg"
+        src={withBase(`/images/foundations/illustration/scene-hero-2.svg`)}
         alt="Scene illustration of a person sitting on a beanbag by a window"
         width="392"
         height="320"
@@ -61,7 +62,7 @@ import Preview from "../../../../components/Preview.astro";
     </div>
     <div class="hero-card">
       <img
-        src="/images/foundations/illustration/scene-hero-3.svg"
+        src={withBase(`/images/foundations/illustration/scene-hero-3.svg`)}
         alt="Scene illustration of a person giving a thumbs up"
         width="472"
         height="305"
@@ -116,7 +117,7 @@ import Preview from "../../../../components/Preview.astro";
   <h3 id="variant-a-examples">Variant A</h3>
   <div class="example-responsive">
     <img
-      src="/images/foundations/illustration/scene-variant-a1.svg"
+      src={withBase(`/images/foundations/illustration/scene-variant-a1.svg`)}
       alt="Variant A scene illustration in a desktop layout"
       width="1045"
       height="1518"
@@ -125,7 +126,7 @@ import Preview from "../../../../components/Preview.astro";
     />
     <div class="example-pair">
       <img
-        src="/images/foundations/illustration/scene-variant-a2.svg"
+        src={withBase(`/images/foundations/illustration/scene-variant-a2.svg`)}
         alt="Variant A scene illustration in a tablet layout"
         width="627"
         height="1809"
@@ -133,7 +134,7 @@ import Preview from "../../../../components/Preview.astro";
         style="max-width: 100%; height: auto;"
       />
       <img
-        src="/images/foundations/illustration/scene-variant-a3.svg"
+        src={withBase(`/images/foundations/illustration/scene-variant-a3.svg`)}
         alt="Variant A scene illustration in a mobile layout"
         width="377"
         height="1809"
@@ -178,7 +179,7 @@ import Preview from "../../../../components/Preview.astro";
   <h3 id="variant-b-examples">Variant B</h3>
   <div class="example-responsive">
     <img
-      src="/images/foundations/illustration/scene-variant-b1.svg"
+      src={withBase(`/images/foundations/illustration/scene-variant-b1.svg`)}
       alt="Variant B scene illustration in a desktop layout"
       width="1037"
       height="986"
@@ -187,7 +188,7 @@ import Preview from "../../../../components/Preview.astro";
     />
     <div class="example-pair">
       <img
-        src="/images/foundations/illustration/scene-variant-b2.svg"
+        src={withBase(`/images/foundations/illustration/scene-variant-b2.svg`)}
         alt="Variant B scene illustration in a tablet layout"
         width="618"
         height="1623"
@@ -195,7 +196,7 @@ import Preview from "../../../../components/Preview.astro";
         style="max-width: 100%; height: auto;"
       />
       <img
-        src="/images/foundations/illustration/scene-variant-b3.svg"
+        src={withBase(`/images/foundations/illustration/scene-variant-b3.svg`)}
         alt="Variant B scene illustration in a mobile layout"
         width="382"
         height="1624"
@@ -216,7 +217,7 @@ import Preview from "../../../../components/Preview.astro";
     >
       <Preview>
         <img
-          src="/images/foundations/illustration/scene-do-landing.png"
+          src={withBase(`/images/foundations/illustration/scene-do-landing.png`)}
           alt="Scene illustration correctly used on a landing page"
           width="743"
           height="534"
@@ -232,7 +233,7 @@ import Preview from "../../../../components/Preview.astro";
     >
       <Preview>
         <img
-          src="/images/foundations/illustration/scene-dont-instructional.png"
+          src={withBase(`/images/foundations/illustration/scene-dont-instructional.png`)}
           alt="Scene illustration incorrectly used in an instructional section"
           width="561"
           height="560"
@@ -248,7 +249,7 @@ import Preview from "../../../../components/Preview.astro";
     >
       <Preview>
         <img
-          src="/images/foundations/illustration/scene-do-unmodified.png"
+          src={withBase(`/images/foundations/illustration/scene-do-unmodified.png`)}
           alt="Scene illustration used as provided in the design system"
           width="724"
           height="314"
@@ -264,7 +265,7 @@ import Preview from "../../../../components/Preview.astro";
     >
       <Preview>
         <img
-          src="/images/foundations/illustration/scene-dont-recoloured.png"
+          src={withBase(`/images/foundations/illustration/scene-dont-recoloured.png`)}
           alt="Scene illustration with colours incorrectly modified"
           width="732"
           height="318"
@@ -280,7 +281,7 @@ import Preview from "../../../../components/Preview.astro";
     >
       <Preview>
         <img
-          src="/images/foundations/illustration/scene-do-matching.png"
+          src={withBase(`/images/foundations/illustration/scene-do-matching.png`)}
           alt="Scene illustration matching the page content"
           width="714"
           height="512"
@@ -296,7 +297,7 @@ import Preview from "../../../../components/Preview.astro";
     >
       <Preview>
         <img
-          src="/images/foundations/illustration/scene-dont-mismatched.png"
+          src={withBase(`/images/foundations/illustration/scene-dont-mismatched.png`)}
           alt="Scene illustration that does not match the page content"
           width="708"
           height="508"
diff --git a/docs/src/pages/foundations/style-guide/illustrations/spot.astro b/docs/src/pages/foundations/style-guide/illustrations/spot.astro
index 2664ef863f..6a77631027 100644
--- a/docs/src/pages/foundations/style-guide/illustrations/spot.astro
+++ b/docs/src/pages/foundations/style-guide/illustrations/spot.astro
@@ -1,4 +1,5 @@
 ---
+import { withBase } from '@/lib/base-url';
 /**
  * Foundations - Style guide - Illustrations - Spot
  *
@@ -60,7 +61,7 @@ import Preview from "../../../../components/Preview.astro";
   </goa-text>
 
   <img
-    src="/images/foundations/illustration/spot-categories.svg"
+    src={withBase(`/images/foundations/illustration/spot-categories.svg`)}
     alt="Examples of spot illustrations across functional categories"
     width="1512"
     height="583"
@@ -98,7 +99,7 @@ import Preview from "../../../../components/Preview.astro";
   <h2 id="examples">Examples</h2>
 
   <img
-    src="/images/foundations/illustration/spot-example-landing.svg"
+    src={withBase(`/images/foundations/illustration/spot-example-landing.svg`)}
     alt="Example of spot illustrations used on a service landing page"
     width="1520"
     height="1872"
@@ -106,7 +107,7 @@ import Preview from "../../../../components/Preview.astro";
     style="max-width: 100%; height: auto;"
   />
   <img
-    src="/images/foundations/illustration/spot-example-empty-state.svg"
+    src={withBase(`/images/foundations/illustration/spot-example-empty-state.svg`)}
     alt="Example of a spot illustration used in an empty state"
     width="1520"
     height="681"
@@ -125,7 +126,7 @@ import Preview from "../../../../components/Preview.astro";
     >
       <Preview>
         <img
-          src="/images/foundations/illustration/spot-do-size.png"
+          src={withBase(`/images/foundations/illustration/spot-do-size.png`)}
           alt="Spot illustration at correct intended size"
           width="545"
           height="397"
@@ -141,7 +142,7 @@ import Preview from "../../../../components/Preview.astro";
     >
       <Preview>
         <img
-          src="/images/foundations/illustration/spot-dont-size.png"
+          src={withBase(`/images/foundations/illustration/spot-dont-size.png`)}
           alt="Spot illustration scaled too small"
           width="545"
           height="318"
@@ -157,7 +158,7 @@ import Preview from "../../../../components/Preview.astro";
     >
       <Preview>
         <img
-          src="/images/foundations/illustration/spot-do-style.png"
+          src={withBase(`/images/foundations/illustration/spot-do-style.png`)}
           alt="Spot illustration using the correct design system style"
           width="417"
           height="404"
@@ -173,7 +174,7 @@ import Preview from "../../../../components/Preview.astro";
     >
       <Preview>
         <img
-          src="/images/foundations/illustration/spot-dont-style.png"
+          src={withBase(`/images/foundations/illustration/spot-dont-style.png`)}
           alt="Spot illustration incorrectly recoloured"
           width="545"
           height="396"
@@ -189,7 +190,7 @@ import Preview from "../../../../components/Preview.astro";
     >
       <Preview>
         <img
-          src="/images/foundations/illustration/spot-do-spacing.png"
+          src={withBase(`/images/foundations/illustration/spot-do-spacing.png`)}
           alt="Spot illustration with correct spacing"
           width="401"
           height="420"
@@ -205,7 +206,7 @@ import Preview from "../../../../components/Preview.astro";
     >
       <Preview>
         <img
-          src="/images/foundations/illustration/spot-dont-spacing.png"
+          src={withBase(`/images/foundations/illustration/spot-dont-spacing.png`)}
           alt="Spot illustration with text placed too close"
           width="401"
           height="372"
@@ -221,7 +222,7 @@ import Preview from "../../../../components/Preview.astro";
     >
       <Preview>
         <img
-          src="/images/foundations/illustration/spot-do-match.png"
+          src={withBase(`/images/foundations/illustration/spot-do-match.png`)}
           alt="Spot illustration matching the user's context"
           width="401"
           height="396"
@@ -237,7 +238,7 @@ import Preview from "../../../../components/Preview.astro";
     >
       <Preview>
         <img
-          src="/images/foundations/illustration/spot-dont-match.png"
+          src={withBase(`/images/foundations/illustration/spot-dont-match.png`)}
           alt="Wrong illustration type used for the context"
           width="401"
           height="400"
diff --git a/docs/src/pages/foundations/style-guide/layout.astro b/docs/src/pages/foundations/style-guide/layout.astro
index 5f867f32b5..db06f04c98 100644
--- a/docs/src/pages/foundations/style-guide/layout.astro
+++ b/docs/src/pages/foundations/style-guide/layout.astro
@@ -1,4 +1,5 @@
 ---
+import { withBase } from '@/lib/base-url';
 /**
  * Foundations - Style guide - Layout
  *
@@ -97,16 +98,16 @@ import FoundationsSupportCallout from "../../../components/FoundationsSupportCal
     </ul>
   </goa-text>
   <goa-text size="body-m" mt="none" mb="l">
-    <a href="/examples/public-form">View Public form documentation</a>
+    <a href={withBase(`/examples/public-form`)}>View Public form documentation</a>
   </goa-text>
   <img
-    src="/images/foundations/style-guide/public-form-1.svg"
+    src={withBase(`/images/foundations/style-guide/public-form-1.svg`)}
     alt="Public form start page"
     width="500"
     height="592"
   />
   <img
-    src="/images/foundations/style-guide/public-form-2.svg"
+    src={withBase(`/images/foundations/style-guide/public-form-2.svg`)}
     alt="Public form example question"
     width="500"
     height="246"
@@ -155,22 +156,22 @@ import FoundationsSupportCallout from "../../../components/FoundationsSupportCal
     </ul>
   </goa-text>
   <goa-text size="body-m" mt="none" mb="l">
-    <a href="/examples/workspace">View Workspace documentation</a>
+    <a href={withBase(`/examples/workspace`)}>View Workspace documentation</a>
   </goa-text>
   <img
-    src="/images/foundations/style-guide/workspace-1.svg"
+    src={withBase(`/images/foundations/style-guide/workspace-1.svg`)}
     alt="Workspace table view"
     width="500"
     height="324"
   />
   <img
-    src="/images/foundations/style-guide/workspace-2.svg"
+    src={withBase(`/images/foundations/style-guide/workspace-2.svg`)}
     alt="Workspace dashboard view"
     width="500"
     height="278"
   /><br />
   <img
-    src="/images/foundations/style-guide/workspace-3.svg"
+    src={withBase(`/images/foundations/style-guide/workspace-3.svg`)}
     alt="Workspace list view"
     width="164"
     height="452"
diff --git a/docs/src/pages/foundations/style-guide/logo.astro b/docs/src/pages/foundations/style-guide/logo.astro
index a0b4384d23..ecbfb60947 100644
--- a/docs/src/pages/foundations/style-guide/logo.astro
+++ b/docs/src/pages/foundations/style-guide/logo.astro
@@ -1,4 +1,5 @@
 ---
+import { withBase } from '@/lib/base-url';
 /**
  * Foundations - Style guide - Logo
  *
@@ -38,7 +39,7 @@ import FoundationsSupportCallout from '../../../components/FoundationsSupportCal
     These elements work together to represent the Alberta brand.
   </goa-text>
   <img
-    src="/images/foundations/style-guide/logo-anatomy.svg"
+    src={withBase(`/images/foundations/style-guide/logo-anatomy.svg`)}
     alt="Diagram showing Alberta logo anatomy, including the wordmark and symbol."
     width="354"
     height="352"
@@ -56,7 +57,7 @@ import FoundationsSupportCallout from '../../../components/FoundationsSupportCal
     Design System components already include the Alberta logo where appropriate.
   </goa-text>
   <img
-    src="/images/foundations/style-guide/primary-usage-logo.svg"
+    src={withBase(`/images/foundations/style-guide/primary-usage-logo.svg`)}
     alt="Primary Alberta logo with stone grey wordmark and sky blue symbol."
     width="500"
     height="120"
@@ -75,7 +76,7 @@ import FoundationsSupportCallout from '../../../components/FoundationsSupportCal
     the symbol.
   </goa-text>
   <img
-    src="/images/foundations/style-guide/reverse-version-logo.svg"
+    src={withBase(`/images/foundations/style-guide/reverse-version-logo.svg`)}
     alt="Reverse version of the Alberta logo for dark backgrounds."
     width="500"
     height="119"
@@ -87,7 +88,7 @@ import FoundationsSupportCallout from '../../../components/FoundationsSupportCal
     official Alberta brand colours.
   </goa-text>
   <img
-    src="/images/foundations/style-guide/white-version-logo.svg"
+    src={withBase(`/images/foundations/style-guide/white-version-logo.svg`)}
     alt="White version of the Alberta logo."
     width="500"
     height="119"
@@ -98,7 +99,7 @@ import FoundationsSupportCallout from '../../../components/FoundationsSupportCal
     Use the black version when colour is not available.
   </goa-text>
   <img
-    src="/images/foundations/style-guide/black-version-logo.svg"
+    src={withBase(`/images/foundations/style-guide/black-version-logo.svg`)}
     alt="Black version of the Alberta logo."
     width="500"
     height="119"
@@ -114,7 +115,7 @@ import FoundationsSupportCallout from '../../../components/FoundationsSupportCal
     Do not place text or visual elements within this protected space.
   </goa-text>
   <img
-    src="/images/foundations/style-guide/alberta-service-logo.svg"
+    src={withBase(`/images/foundations/style-guide/alberta-service-logo.svg`)}
     alt="Alberta service logo with required protective spacing."
     width="394"
     height="126"
@@ -127,7 +128,7 @@ import FoundationsSupportCallout from '../../../components/FoundationsSupportCal
     Use the Alberta sub-mark when space is limited.
   </goa-text>
   <img
-    src="/images/foundations/style-guide/alberta-sub-mark.svg"
+    src={withBase(`/images/foundations/style-guide/alberta-sub-mark.svg`)}
     alt="Alberta sub-mark."
     width="139"
     height="139"
diff --git a/docs/src/pages/foundations/style-guide/typography.astro b/docs/src/pages/foundations/style-guide/typography.astro
index b53a11693d..2e912dd520 100644
--- a/docs/src/pages/foundations/style-guide/typography.astro
+++ b/docs/src/pages/foundations/style-guide/typography.astro
@@ -1,4 +1,5 @@
 ---
+import { withBase } from '@/lib/base-url';
 /**
  * Foundations - Style guide - Typography
  *
@@ -49,7 +50,7 @@ import FoundationsSupportCallout from "../../../components/FoundationsSupportCal
 
   <h3 id="text-styles">Text styles</h3>
   <goa-text size="body-m" mt="none" mb="m">
-    The design system provides predefined <a href="/tokens">text styles</a> for headings, paragraphs,
+    The design system provides predefined <a href={withBase(`/tokens`)}>text styles</a> for headings, paragraphs,
     and numeric content.
   </goa-text>
 
diff --git a/docs/src/pages/get-started/component-lifecycle.astro b/docs/src/pages/get-started/component-lifecycle.astro
index 2f43127d7d..42b0df0f4a 100644
--- a/docs/src/pages/get-started/component-lifecycle.astro
+++ b/docs/src/pages/get-started/component-lifecycle.astro
@@ -1,4 +1,5 @@
 ---
+import { withBase } from '@/lib/base-url';
 /**
  * Get Started - Component Lifecycle
  *
@@ -22,7 +23,7 @@ import DocumentationPageLayout from '../../layouts/DocumentationPageLayout.astro
 
   <p>
     To request a new component or propose an enhancement, follow the
-    <a href="/get-started/contribute">design contribution process</a>.
+    <a href={withBase(`/get-started/contribute`)}>design contribution process</a>.
   </p>
   <goa-text as="h2" id="experimental" version="2" size="heading-m">Experimental</goa-text>
   <p>
diff --git a/docs/src/pages/get-started/contribute.astro b/docs/src/pages/get-started/contribute.astro
index 9e006c5426..7a2ea6d675 100644
--- a/docs/src/pages/get-started/contribute.astro
+++ b/docs/src/pages/get-started/contribute.astro
@@ -1,4 +1,5 @@
 ---
+import { withBase } from '@/lib/base-url';
 /**
  * Get Started - Contribute
  *
@@ -26,7 +27,7 @@ import DocumentationPageLayout from '../../layouts/DocumentationPageLayout.astro
   </p>
   <goa-text as="h2" id="design-contribution-process" version="2" size="heading-m">Design contribution process</goa-text>
   <p>
-    If a required <a href="/components">component</a> or <a href="/examples">example</a> does not exist in production,
+    If a required <a href={withBase(`/components`)}>component</a> or <a href={withBase(`/examples`)}>example</a> does not exist in production,
     contact the Design System team. We will review the request together and determine next steps.
   </p>
 
diff --git a/docs/src/pages/get-started/designers.astro b/docs/src/pages/get-started/designers.astro
index 0c47d99114..2d8a3b163d 100644
--- a/docs/src/pages/get-started/designers.astro
+++ b/docs/src/pages/get-started/designers.astro
@@ -1,4 +1,5 @@
 ---
+import { withBase } from '@/lib/base-url';
 /**
  * Get Started - Designers Overview
  *
@@ -21,8 +22,8 @@ import DocumentationPageLayout from '../../layouts/DocumentationPageLayout.astro
   <p>In Figma, you can access:</p>
 
   <ul>
-    <li><a href="/tokens">Design tokens</a></li>
-    <li><a href="/components">Components</a></li>
+    <li><a href={withBase(`/tokens`)}>Design tokens</a></li>
+    <li><a href={withBase(`/components`)}>Components</a></li>
     <li><a href="https://www.figma.com/design/aIRjvBzpIUH0GbkffjbL04/%E2%9D%96-Patterns-library-%7C-DDD?node-id=6345-1491163" target="_blank">Patterns</a></li>
   </ul>
 
diff --git a/docs/src/pages/get-started/developers.astro b/docs/src/pages/get-started/developers.astro
index 7c7cc56977..b34d1c3712 100644
--- a/docs/src/pages/get-started/developers.astro
+++ b/docs/src/pages/get-started/developers.astro
@@ -1,4 +1,5 @@
 ---
+import { withBase } from '@/lib/base-url';
 /**
  * Get Started - Developers Overview
  *
@@ -25,9 +26,9 @@ import DocumentationPageLayout from '../../layouts/DocumentationPageLayout.astro
   </p>
   <p>The Design System includes:</p>
   <ul>
-    <li><a href="/tokens"><strong>Tokens</strong></a></li>
-    <li><a href="/components"><strong>Components</strong></a></li>
-    <li><a href="/examples"><strong>Examples</strong></a></li>
+    <li><a href={withBase(`/tokens`)}><strong>Tokens</strong></a></li>
+    <li><a href={withBase(`/components`)}><strong>Components</strong></a></li>
+    <li><a href={withBase(`/examples`)}><strong>Examples</strong></a></li>
     <li><strong>Templates</strong></li>
   </ul>
   <p>
@@ -65,7 +66,7 @@ import DocumentationPageLayout from '../../layouts/DocumentationPageLayout.astro
     <li>As <a href="https://www.npmjs.com/package/@abgov/react-components" target="_blank">React</a> wrappers</li>
   </ul>
   <p>
-    Refer to the Design System <a href="/get-started/developers/technologies">technologies</a> documentation
+    Refer to the Design System <a href={withBase(`/get-started/developers/technologies`)}>technologies</a> documentation
     for implementation details.
   </p>
 
diff --git a/docs/src/pages/get-started/developers/browsers.astro b/docs/src/pages/get-started/developers/browsers.astro
index 4c495d9c3f..3ced88e5fc 100644
--- a/docs/src/pages/get-started/developers/browsers.astro
+++ b/docs/src/pages/get-started/developers/browsers.astro
@@ -1,4 +1,5 @@
 ---
+import { withBase } from '@/lib/base-url';
 /**
  * Get Started - Developers - Supported browsers
  *
@@ -80,7 +81,7 @@ import DocumentationPageLayout from '../../../layouts/DocumentationPageLayout.as
   <p>
     Use supported browsers and operating system versions when developing and testing services. If you
     encounter a browser-specific issue, follow the
-    <a href="/get-started/developers/bug">Verify a bug</a> process.
+    <a href={withBase(`/get-started/developers/bug`)}>Verify a bug</a> process.
   </p>
   <DropInCallout />
 </DocumentationPageLayout>
diff --git a/docs/src/pages/get-started/developers/technologies.astro b/docs/src/pages/get-started/developers/technologies.astro
index bff58c1150..272d9a8a12 100644
--- a/docs/src/pages/get-started/developers/technologies.astro
+++ b/docs/src/pages/get-started/developers/technologies.astro
@@ -1,4 +1,5 @@
 ---
+import { withBase } from '@/lib/base-url';
 /**
  * Get Started - Developers - Technologies
  *
@@ -29,7 +30,7 @@ import DocumentationPageLayout from '../../../layouts/DocumentationPageLayout.as
     We use Svelte to author the components that are compiled to custom elements. You can use the Design
     System through the core Web Components or through Angular and React wrappers.
   </p>
-  <img src="/images/technologies.svg" alt="Diagram showing the technology layers: Svelte compiles to Web Components, which are wrapped by Angular and React" style="width: 100%; max-width: 700px; margin: var(--goa-space-l) 0;" />
+  <img src={withBase(`/images/technologies.svg`)} alt="Diagram showing the technology layers: Svelte compiles to Web Components, which are wrapped by Angular and React" style="width: 100%; max-width: 700px; margin: var(--goa-space-l) 0;" />
   <goa-text as="h2" id="web-components" version="2" size="heading-m">Web Components</goa-text>
   <p>
     <a href="https://developer.mozilla.org/en-US/docs/Web/API/Web_Components" target="_blank">Web Components</a>
diff --git a/docs/src/pages/get-started/index.astro b/docs/src/pages/get-started/index.astro
index 1b542be742..1b92e400aa 100644
--- a/docs/src/pages/get-started/index.astro
+++ b/docs/src/pages/get-started/index.astro
@@ -1,4 +1,5 @@
 ---
+import { withBase } from '@/lib/base-url';
 /**
  * Get Started - Landing Page
  *
@@ -29,9 +30,9 @@ import DocumentationPageLayout from '../../layouts/DocumentationPageLayout.astro
   <goa-text as="h2" id="design-system-by-role" version="2" size="heading-m">Design system by role</goa-text>
 
   <ul>
-    <li><a href="/get-started/designers">Designer</a></li>
-    <li><a href="/get-started/developers">Developer</a></li>
-    <li><a href="/get-started/qa-testing">QA tester</a></li>
+    <li><a href={withBase(`/get-started/designers`)}>Designer</a></li>
+    <li><a href={withBase(`/get-started/developers`)}>Developer</a></li>
+    <li><a href={withBase(`/get-started/qa-testing`)}>QA tester</a></li>
   </ul>
 
   <goa-text as="h2" id="why-start-with-the-design-system" version="2" size="heading-m">Why start with the design system?</goa-text>
@@ -101,7 +102,7 @@ import DocumentationPageLayout from '../../layouts/DocumentationPageLayout.astro
   </goa-callout>
 
   <goa-link version="2" mb="m">
-    <a href="/get-started/component-lifecycle">View the design system governance process</a>
+    <a href={withBase(`/get-started/component-lifecycle`)}>View the design system governance process</a>
   </goa-link>
   <DropInCallout />
 </DocumentationPageLayout>
diff --git a/docs/src/pages/get-started/migration-guide.astro b/docs/src/pages/get-started/migration-guide.astro
index 06fbbcbe91..b43c6678e3 100644
--- a/docs/src/pages/get-started/migration-guide.astro
+++ b/docs/src/pages/get-started/migration-guide.astro
@@ -1,4 +1,5 @@
 ---
+import { withBase } from '@/lib/base-url';
 /**
  * Get Started - Developers - Migration guide
  *
@@ -224,7 +225,7 @@ import DocumentationPageLayout from "../../layouts/DocumentationPageLayout.astro
   <h2 id="related-guidance">Related guidance</h2>
   <goa-block version="2" gap="s" direction="column">
     <goa-link version="2"
-      ><a href="/get-started/developers">Review the setup steps for developers</a
+      ><a href={withBase(`/get-started/developers`)}>Review the setup steps for developers</a
       ></goa-link
     >
   </goa-block>
diff --git a/docs/src/pages/get-started/out-of-support.astro b/docs/src/pages/get-started/out-of-support.astro
index c341fa8b9c..3944d67e3a 100644
--- a/docs/src/pages/get-started/out-of-support.astro
+++ b/docs/src/pages/get-started/out-of-support.astro
@@ -1,4 +1,5 @@
 ---
+import { withBase } from '@/lib/base-url';
 /**
  * Get Started - Out of Support Versions
  *
@@ -43,7 +44,7 @@ import DocumentationPageLayout from '../../layouts/DocumentationPageLayout.astro
   <goa-text as="h2" id="what-to-do-next" version="2" size="heading-m">What to do next</goa-text>
   <p>
     Upgrade to the latest supported version. Refer to the
-    <a href="/get-started/developers/update">version update guide</a>.
+    <a href={withBase(`/get-started/developers/update`)}>version update guide</a>.
   </p>
   <p>
     If you need support planning your upgrade,
diff --git a/docs/src/pages/index.astro b/docs/src/pages/index.astro
index 2bf12f8dcf..1c720ba5a7 100644
--- a/docs/src/pages/index.astro
+++ b/docs/src/pages/index.astro
@@ -1,4 +1,5 @@
 ---
+import { withBase } from '@/lib/base-url';
 /**
  * Home Page
  *
@@ -14,7 +15,7 @@ import CardLite from '../components/CardLite.astro';
   <div class="ds-hero-banner">
     <div class="hero-content">
       <div class="hero-image">
-        <img src="/images/home/hero-banner-graphic.svg" alt="" />
+        <img src={withBase(`/images/home/hero-banner-graphic.svg`)} alt="" />
       </div>
       <div class="hero-text">
         <h1>A design system for Alberta government digital services</h1>
@@ -50,11 +51,11 @@ import CardLite from '../components/CardLite.astro';
           Our accessible, brand-compliant components and templates help you launch faster while staying aligned with the current standard.
         </p>
         <goa-link version="2" trailingicon="arrow-forward">
-          <a href="/get-started">Start using the design system</a>
+          <a href={withBase(`/get-started`)}>Start using the design system</a>
         </goa-link>
       </div>
       <div class="cta-image">
-        <img src="/images/home/splash-reel.png" alt="" />
+        <img src={withBase(`/images/home/splash-reel.png`)} alt="" />
       </div>
     </div>
 
@@ -62,16 +63,16 @@ import CardLite from '../components/CardLite.astro';
     <h2 class="section-heading">Select your service pattern</h2>
     <div class="card-grid two-col">
       <CardLite
-        imageUrl="/images/home/public-form-thumb.png"
+        imageUrl={withBase(`/images/home/public-form-thumb.png`)}
         title="Public form"
         description="A pattern optimized for clarity and error prevention for public-facing applications. It includes templates for page types: Start, Task list, Question, Review, and Result."
-        linkTo="/examples/public-form"
+        linkTo={withBase(`/examples/public-form`)}
       />
       <CardLite
-        imageUrl="/images/home/workspace-thumb.png"
+        imageUrl={withBase(`/images/home/workspace-thumb.png`)}
         title="Workspace"
         description="A pattern optimized for efficiently managing cases, records, and tasks. It includes layout, multiple data views, detail views, drawers, modals and notifications."
-        linkTo="/examples/workspace"
+        linkTo={withBase(`/examples/workspace`)}
       />
     </div>
 
@@ -102,19 +103,19 @@ import CardLite from '../components/CardLite.astro';
     </p>
     <div class="card-grid three-col">
       <CardLite
-        imageUrl="/images/home/primary-users-thumb.png"
+        imageUrl={withBase(`/images/home/primary-users-thumb.png`)}
         title="Identify the primary users and their main tasks"
         description="Share the primary users and their main tasks in your digital service. Do you know your users?"
         linkTo="https://forms.cloud.microsoft/r/qz8XKnbcsE"
       />
       <CardLite
-        imageUrl="/images/home/storyboard-thumb.png"
+        imageUrl={withBase(`/images/home/storyboard-thumb.png`)}
         title="Identify the main pages"
         description="Share the most used pages from your digital service. What page or pages define your service?"
         linkTo="https://forms.cloud.microsoft/r/aq7SCVtEg8"
       />
       <CardLite
-        imageUrl="/images/home/main-pages-thumb.png"
+        imageUrl={withBase(`/images/home/main-pages-thumb.png`)}
         title="Create a short storyboard"
         description="You can only use 3 pages from your product to make a storyboard of your digital service, what do you show?"
         linkTo="https://forms.cloud.microsoft/r/vbhkWQnTyP"