@eox/pages-theme-eox 2.0.0-alpha.5 → 2.0.0-alpha.7

package/.gitlab-ci.yml

@@ -10,9 +10,11 @@ cache:
       - package-lock.json
   paths:
     - .npm/
+    - .cache/Cypress
 
 variables:
   npm_config_cache: "$CI_PROJECT_DIR/.npm"
+  CYPRESS_CACHE_FOLDER: "$CI_PROJECT_DIR/.cache/Cypress"
 
 security:
   stage: security
@@ -33,6 +35,7 @@ test:
   stage: test
   script:
     - npm ci
-    - npm run test:component
+    - npx cypress install
+    - npm run test
   rules:
     - if: $CI_PIPELINE_SOURCE == 'merge_request_event' && $CI_MERGE_REQUEST_TARGET_BRANCH_NAME == 'main'

package/README.md

@@ -21,6 +21,45 @@ See also the [Vitepress Docs](https://vitepress.dev/guide/custom-theme#consuming
 
 This theme supports standard [VitePress Default Theme Configuration](https://vitepress.dev/reference/default-theme-config) with some specific adaptations.
 
+### LLMs Configuration (`llms.txt`)
+
+This theme integrates [vitepress-plugin-llms](https://github.com/nmoodev/vitepress-plugin-llms) to automatically generate AI-friendly documentation (`llms.txt` and `llms-full.txt`), along with custom support for VitePress story routes and remote story manifests.
+
+Generation is enabled by default. You can configure options via `brandConfig.llms` in your brand configuration:
+
+```javascript
+// Example brandConfig:
+export const config = {
+  // ... other brand settings ...
+  llms: {
+    // Upstream vitepress-plugin-llms options
+    domain: "https://yourdomain.com", // Base URL to resolve absolute links in llms.txt
+    copyButtons: true, // (Optional) Adds copy buttons to code blocks in documentation
+
+    // Theme-specific Story Routes config
+    stories: {
+      heading: "Stories", // (Optional) Heading used in llms.txt and route pages (default: "Stories")
+      path: "narratives/[narrative]", // (Optional) Story route pattern (e.g. "narratives/[narrative]" or "story"). Also accepts `storyPath`
+      manifest: "https://cdn.example.com/narratives.json", // (Optional) URL to stories manifest (auto-detected from gallery components if omitted)
+      concurrency: 8, // (Optional) Maximum concurrent story downloads (default: 8)
+    },
+  },
+};
+```
+
+#### Disabling LLMs
+
+- To disable LLM documentation generation entirely: set `llms: false`.
+- To generate general docs without stories: set `stories: false` inside `llms`:
+
+```javascript
+export const config = {
+  llms: {
+    stories: false,
+  },
+};
+```
+
 ### Navigation Bar
 
 The Navigation Bar follows the [Default Theme Nav](https://vitepress.dev/reference/default-theme-nav) structure with the following differences:
@@ -572,7 +611,14 @@ feedback: false
 The theme exports a set of shared utility and helper functions from its helpers module. You can import and use these helpers in your custom VitePress components, checkout pages, or inline script setups:
 
 ```javascript
-import { formatPrice, trackEvent, t } from "@eox/pages-theme-eox/src/helpers";
+import {
+  formatPrice,
+  trackEvent,
+  trackPageView,
+  trackSiteSearch,
+  normalizeTrackingUrl,
+  t,
+} from "@eox/pages-theme-eox/src/helpers";
 ```
 
 ### Available Helpers
@@ -598,12 +644,12 @@ formatPrice(12000, "en"); // "€ 12,000.-"
 formatPrice(49.99, "de"); // "€ 49,99"
 ```
 
-#### `trackEvent(eventDetails)`
+#### `trackEvent(eventDetails, ...rest)`
 
-Sends a custom tracking event to Matomo Analytics.
+Sends a custom tracking event to Matomo Analytics. Automatically normalizes any path strings passed in category, action, or name.
 
 - **Parameters**:
-  - `eventDetails` (`Array<string>`): An array representing the event payload: `[Category, Action, Name?, Value?]`.
+  - `eventDetails` (`Array<string|number>|string`): An array `[Category, Action, Name?, Value?]` or positional arguments `(category, action, name, value)`.
 
 ##### Example Usage:
 
@@ -611,8 +657,51 @@ Sends a custom tracking event to Matomo Analytics.
 import { trackEvent } from "@eox/pages-theme-eox/src/helpers";
 
 trackEvent(["CTA", "Click", "Technical Specifications", "Viewing Ready"]);
+trackEvent("indicators", "select_indicator", "N1_NO2");
+```
+
+#### `trackPageView(options)`
+
+Tracks a pageview with normalized path (trailing slash stripped, transient parameters removed) and custom document title.
+
+- **Parameters**:
+  - `options` (`Object|string`): Vitepress router object, `{ path, title }` options object, or custom path string.
+
+##### Example Usage:
+
+```javascript
+import { trackPageView } from "@eox/pages-theme-eox/src/helpers";
+
+trackPageView({ path: "/explore/", title: "Explore" });
+// Sends normalized URL "/explore" to Matomo
+```
+
+#### `trackSiteSearch(keyword, category, resultsCount)`
+
+Sends search keyword telemetry to Matomo Site Search reports.
+
+- **Parameters**:
+  - `keyword` (`string`): Searched term.
+  - `category` (`string|boolean`): Category (optional, e.g. `'indicators'`, `'stories'`).
+  - `resultsCount` (`number`): Number of search results returned.
+
+##### Example Usage:
+
+```javascript
+import { trackSiteSearch } from "@eox/pages-theme-eox/src/helpers";
+
+trackSiteSearch("methane", "indicators", 4);
 ```
 
+#### `normalizeTrackingUrl(inputUrl, options)`
+
+Pure helper that strips trailing slashes (e.g., `/explore/` -> `/explore`), strips volatile coordinate query params (`x`, `y`, `z`), and sorts remaining query parameters.
+
+- **Parameters**:
+  - `inputUrl` (`string`): URL or path to normalize.
+  - `options` (`Object`): Optional configuration (`ignoredParams`, `stripTrailingSlash`).
+- **Returns**: `string` - Normalized URL string.
+
 #### `t(key, i18n)`
 
 Retrieves localized translation strings from an i18n mapping object using dot-notation. Falls back to the key itself if no translation is defined.

package/cypress/support/mocks/authors.data.js

@@ -0,0 +1,14 @@
+export const data = [
+  {
+    id: "mock-author-1",
+    name: "Mock Author 1",
+    url: "/team/mock-author-1",
+    guest: false,
+  },
+  {
+    id: "mock-author-2",
+    name: "Mock Author 2",
+    url: "/team/mock-author-2",
+    guest: false,
+  },
+];

package/cypress/support/mocks/helpers.js

@@ -1,7 +1,40 @@
 // Mock generic helpers
 // We delegate to a global object to allow spying in tests
 window.__helpersMock = {
-  trackEvent: (details) => {},
+  trackEvent: (details, ...rest) => {},
+  trackPageView: (options) => {},
+  trackSiteSearch: (keyword, category, count) => {},
+  normalizeTrackingUrl: (url, options) => {
+    if (!url || typeof url !== "string") return url;
+    const { ignoredParams = ["x", "y", "z"], stripTrailingSlash = true } =
+      options || {};
+    try {
+      const base =
+        typeof window !== "undefined" && window.location?.href
+          ? window.location.href
+          : "https://eox.at";
+      const u = new URL(url, base);
+      let pathname = u.pathname;
+      if (stripTrailingSlash && pathname.length > 1 && pathname.endsWith("/")) {
+        pathname = pathname.replace(/\/+$/, "");
+      }
+      const searchParams = new URLSearchParams(u.search);
+      for (const key of ignoredParams) {
+        searchParams.delete(key);
+      }
+      searchParams.sort();
+      const search = searchParams.toString();
+      const isRelative = !/^https?:\/\//i.test(url);
+      if (isRelative) {
+        return pathname + (search ? `?${search}` : "");
+      }
+      u.pathname = pathname;
+      u.search = search ? `?${search}` : "";
+      return u.toString();
+    } catch {
+      return url;
+    }
+  },
   acceptCookies: (router) => {},
   declineCookies: (router) => {},
   enableTracking: (enable, router) => {},
@@ -94,6 +127,12 @@ window.__helpersMock = {
 };
 
 export const trackEvent = (...args) => window.__helpersMock.trackEvent(...args);
+export const trackPageView = (...args) =>
+  window.__helpersMock.trackPageView(...args);
+export const trackSiteSearch = (...args) =>
+  window.__helpersMock.trackSiteSearch(...args);
+export const normalizeTrackingUrl = (...args) =>
+  window.__helpersMock.normalizeTrackingUrl(...args);
 export const acceptCookies = (...args) =>
   window.__helpersMock.acceptCookies(...args);
 export const declineCookies = (...args) =>

package/cypress.config.js

@@ -34,6 +34,15 @@ export default defineConfig({
               __dirname,
               "cypress/support/mocks/features.data.js",
             ),
+            // Alias authors.data.js to our mock
+            "../authors.data.js": path.resolve(
+              __dirname,
+              "cypress/support/mocks/authors.data.js",
+            ),
+            "../../authors.data.js": path.resolve(
+              __dirname,
+              "cypress/support/mocks/authors.data.js",
+            ),
           },
         },
         plugins: [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@eox/pages-theme-eox",
-  "version": "2.0.0-alpha.5",
+  "version": "2.0.0-alpha.7",
   "type": "module",
   "description": "Vitepress Theme with EOX branding",
   "main": "src/index.js",
@@ -12,6 +12,8 @@
   "scripts": {
     "format": "npx prettier --write .",
     "format:check": "npx prettier --check .",
+    "test": "npm run test:unit && npm run test:component",
+    "test:unit": "node --test src/helpers.test.js src/llms/llms.test.js",
     "test:component": "cypress run --component",
     "release": "release-it"
   },
@@ -19,7 +21,8 @@
     "@eox/eslint-config": "^2.0.0",
     "@eox/feedback": "^1.1.1",
     "@eox/ui": "^1.0.1",
-    "vitepress": "^1.6.3"
+    "vitepress": "^1.6.3",
+    "vitepress-plugin-llms": "^1.13.5"
   },
   "devDependencies": {
     "@release-it/conventional-changelog": "^10.0.6",

package/src/components/BlogPost.vue

@@ -191,7 +191,19 @@ const coverImage = computed(() => {
 
 // Dynamic Recent Posts (excluding current page)
 const calculatedRecentPosts = computed(() => {
-  return posts.filter((p) => p.url !== page.value.url).slice(0, 5);
+  const rel = page.value.relativePath || "";
+  const current = (
+    "/" + rel.replace(/(^|\/)index\.md$/, "$1").replace(/\.md$/, "")
+  )
+    .replace(/\/$/, "")
+    .replace(/\.html$/, "");
+
+  return posts
+    .filter((p) => {
+      const pUrl = (p.url || "").replace(/\/$/, "").replace(/\.html$/, "");
+      return pUrl !== current && p.title !== frontmatter.value.title;
+    })
+    .slice(0, 5);
 });
 
 // Dynamic Hot Tags

package/src/components/FeatureSection.cy.js

@@ -1,3 +1,4 @@
+import { h } from "vue";
 import FeatureSection from "./FeatureSection.vue";
 
 describe("<FeatureSection />", () => {
@@ -60,4 +61,19 @@ describe("<FeatureSection />", () => {
     cy.get(".feature-section").should("have.class", "dark");
     cy.get(".feature-section").should("have.class", "reverse");
   });
+
+  it("has padding-block-start 0 when following a title", () => {
+    const TestWrapper = {
+      render() {
+        return h("div", [
+          h("h2", "Products & Services"),
+          h("p", "Subtitle paragraph"),
+          h(FeatureSection, defaultProps),
+        ]);
+      },
+    };
+
+    cy.mount(TestWrapper);
+    cy.get(".feature-section").should("have.css", "padding-top", "0px");
+  });
 });

package/src/components/Footer.cy.js

@@ -107,4 +107,16 @@ describe("<Footer />", () => {
       .should("have.attr", "href", "https://eox.at")
       .and("contain", "EOX");
   });
+
+  it("defines hover underline styles for footer links", () => {
+    cy.mount(Footer);
+    cy.get("footer .link").should("have.css", "text-decoration-line", "none");
+    cy.document().then((doc) => {
+      const styles = Array.from(doc.querySelectorAll("style"))
+        .map((s) => s.textContent)
+        .join("\n");
+      expect(styles).to.include("footer .link:hover");
+      expect(styles).to.include("text-decoration: underline");
+    });
+  });
 });

package/src/components/Footer.vue

@@ -136,10 +136,17 @@ footer .grid > div:not(:first-child) p,
   margin: 0 !important;
 }
 
+footer a:not(.button),
 footer .link {
   text-decoration: none;
 }
 
+footer a:not(.button):hover,
+footer .link:hover {
+  text-decoration: underline;
+  text-underline-offset: 2px;
+}
+
 .footer-columns {
   columns: 1;
   column-gap: 2rem;

package/src/components/MobileNavDropdown.vue

@@ -46,3 +46,10 @@ defineProps({
 const route = useRoute();
 const { theme } = useData();
 </script>
+
+<style scoped>
+a,
+a:hover {
+  text-decoration: none !important;
+}
+</style>

package/src/components/NavDropdown.vue

@@ -60,3 +60,10 @@ defineProps({
 const route = useRoute();
 const { theme } = useData();
 </script>
+
+<style scoped>
+a,
+a:hover {
+  text-decoration: none !important;
+}
+</style>

package/src/components/TestimonialsSection.cy.js

@@ -5,10 +5,7 @@ describe("<TestimonialsSection />", () => {
     cy.mount(TestimonialsSection);
 
     // Verify title
-    cy.get(".section-display-title").should(
-      "contain",
-      "What our customers are saying",
-    );
+    cy.get(".headline h2").should("contain", "What our customers are saying");
 
     // Verify first testimonial quote
     cy.get(".quote-text").should(
@@ -61,7 +58,7 @@ describe("<TestimonialsSection />", () => {
     });
 
     // Check title
-    cy.get(".section-display-title").should("contain", customTitle);
+    cy.get(".headline h2").should("contain", customTitle);
 
     // Check first custom testimonial
     cy.get(".quote-text").should("contain", "This is a custom quote");

package/src/helpers.js

@@ -1,28 +1,157 @@
 import { watch } from "vue";
 
 /**
- * Track Matomo event with array of four primary components
+ * Normalizes a URL / path for tracking by:
+ * - Removing trailing slash (e.g. `/explore/` -> `/explore`, except for root `/`)
+ * - Stripping transient / high-cardinality UI params (e.g., coordinates `x`, `y`, `z`)
+ * - Sorting remaining query parameters alphabetically
  *
- * - Category (Required) – This describes the type of events you want to track. For example, Link Clicks, Videos, Outbound Links, and Form Events.
- * - Action (Required) – This is the specific action that is taken. For example, with the Video category, you might have a Play, Pause and Complete action.
- * - Name (Optional – Recommended) – This is usually the title of the element that is being interacted with, to aid with analysis. For example, it could be the name of a Video that was played or the specific form that is being submitted.
- * - Value (Optional) – This is a numeric value and is often added dynamically. It could be the cost of a product that is added to a cart, or the completion percentage of a video.
+ * @param {string} inputUrl - The URL or relative path to normalize
+ * @param {Object} [options] - Normalization options
+ * @param {Array<string>} [options.ignoredParams] - Query parameter keys to strip
+ * @param {boolean} [options.stripTrailingSlash=true] - Whether to strip trailing slashes
+ * @returns {string} Normalized URL / path
+ */
+export const normalizeTrackingUrl = (inputUrl, options = {}) => {
+  if (!inputUrl || typeof inputUrl !== "string") return inputUrl;
+  const { ignoredParams = ["x", "y", "z"], stripTrailingSlash = true } =
+    options;
+
+  try {
+    const base =
+      typeof window !== "undefined" && window.location?.href
+        ? window.location.href
+        : "https://eox.at";
+    const url = new URL(inputUrl, base);
+    let pathname = url.pathname;
+
+    if (stripTrailingSlash && pathname.length > 1 && pathname.endsWith("/")) {
+      pathname = pathname.replace(/\/+$/, "");
+    }
+
+    const searchParams = new URLSearchParams(url.search);
+    for (const key of ignoredParams) {
+      searchParams.delete(key);
+    }
+    searchParams.sort();
+
+    const search = searchParams.toString();
+    const isRelativeInput = !/^https?:\/\//i.test(inputUrl);
+
+    if (isRelativeInput) {
+      return pathname + (search ? `?${search}` : "");
+    }
+    url.pathname = pathname;
+    url.search = search ? `?${search}` : "";
+    return url.toString();
+  } catch {
+    if (stripTrailingSlash && inputUrl.length > 1 && inputUrl.endsWith("/")) {
+      return inputUrl.replace(/\/+$/, "");
+    }
+    return inputUrl;
+  }
+};
+
+/**
+ * Track Matomo event with array or positional arguments of four primary components:
+ * Category, Action, Name (optional), Value (optional)
+ *
+ * Automatically normalizes any path parameters (e.g., Action or Name).
  *
  * See https://matomo.org/faq/reports/the-anatomy-of-an-event/
  *
- * @param {Array<string>} eventDetails
+ * @param {Array<string|number>|string} eventDetails - Array of event details or Category string
+ * @param {...*} rest - Remaining event details if passed positionally
+ */
+export const trackEvent = (eventDetails, ...rest) => {
+  if (typeof window === "undefined") return;
+  const _paq = (window._paq = window._paq || []);
+
+  const details = Array.isArray(eventDetails)
+    ? [...eventDetails]
+    : [eventDetails, ...rest];
+
+  if (typeof details[1] === "string" && details[1].startsWith("/")) {
+    details[1] = normalizeTrackingUrl(details[1]);
+  }
+  if (typeof details[2] === "string" && details[2].startsWith("/")) {
+    details[2] = normalizeTrackingUrl(details[2]);
+  }
+
+  _paq.push(["trackEvent", ...details]);
+};
+
+/**
+ * Track page view with normalized URL and standardized document title.
+ *
+ * @param {Object|string} [options] - Router instance, options object, or path string
+ * @param {string} [options.path] - Custom path to track
+ * @param {string} [options.title] - Custom document title to track
+ * @param {Object} [options.route] - VitePress router route object
  */
-export const trackEvent = (eventDetails) => {
-  if (!import.meta.env.SSR) {
-    _paq.push(["trackEvent", ...eventDetails]);
+export const trackPageView = (options = {}) => {
+  if (typeof window === "undefined") return;
+  const _paq = (window._paq = window._paq || []);
+
+  let rawPath = "";
+  let rawTitle = "";
+
+  if (typeof options === "string") {
+    rawPath = options;
+  } else if (options && typeof options === "object") {
+    if (options.route) {
+      rawPath = options.route.path;
+      rawTitle = options.route.data?.title;
+    } else {
+      rawPath =
+        options.path ||
+        options.customUrl ||
+        (typeof window !== "undefined"
+          ? window.location.pathname + window.location.search
+          : "");
+      rawTitle =
+        options.title ||
+        options.customTitle ||
+        (typeof document !== "undefined" ? document.title : "");
+    }
+  }
+
+  const normalizedUrl = normalizeTrackingUrl(rawPath);
+  if (normalizedUrl) {
+    _paq.push(["setCustomUrl", normalizedUrl]);
   }
+  if (rawTitle) {
+    _paq.push(["setDocumentTitle", rawTitle.trim()]);
+  }
+  _paq.push(["trackPageView"]);
+  _paq.push(["enableLinkTracking"]);
+};
+
+/**
+ * Track site search keyword query in Matomo.
+ *
+ * @param {string} keyword - Searched term
+ * @param {string|boolean} [category=false] - Search category (e.g. 'stories', 'indicators')
+ * @param {number} [resultsCount=0] - Number of search results found
+ */
+export const trackSiteSearch = (
+  keyword,
+  category = false,
+  resultsCount = 0,
+) => {
+  if (typeof window === "undefined") return;
+  const _paq = (window._paq = window._paq || []);
+  _paq.push(["trackSiteSearch", keyword, category, resultsCount]);
 };
 
 /**
  * Accept cookies
  */
 export const acceptCookies = (router) => {
-  _paq.push(["rememberCookieConsentGiven"]);
+  if (typeof window !== "undefined") {
+    const _paq = (window._paq = window._paq || []);
+    _paq.push(["rememberCookieConsentGiven"]);
+  }
   showBanner(false);
   enableTracking(true, router);
 };
@@ -31,8 +160,11 @@ export const acceptCookies = (router) => {
  * Decline cookies
  */
 export const declineCookies = (router) => {
-  _paq.push(["forgetCookieConsentGiven"]);
-  _paq.push(["optUserOut"]);
+  if (typeof window !== "undefined") {
+    const _paq = (window._paq = window._paq || []);
+    _paq.push(["forgetCookieConsentGiven"]);
+    _paq.push(["optUserOut"]);
+  }
   showBanner(false);
   enableTracking(false, router);
 };
@@ -60,17 +192,24 @@ export const enableTracking = (enabled, router) => {
 };
 
 /**
- * Track page scrolling depth
+ * Track page scrolling depth with normalized path and numeric depth values.
  *
  * @param enabled Boolean
+ * @param router VitePress router
  */
 export const trackPageScrolling = (enabled, router) => {
   function getScrollPercent() {
-    const h = document.documentElement,
-      b = document.body,
-      st = "scrollTop",
-      sh = "scrollHeight";
-    return ((h[st] || b[st]) / ((h[sh] || b[sh]) - h.clientHeight)) * 100;
+    try {
+      const h = document.documentElement,
+        b = document.body,
+        st = "scrollTop",
+        sh = "scrollHeight";
+      const scrollable = (h[sh] || b[sh]) - h.clientHeight;
+      if (scrollable <= 0) return 0;
+      return ((h[st] || b[st]) / scrollable) * 100;
+    } catch {
+      return 0;
+    }
   }
   const scrollTargets = {
     25: [],
@@ -79,17 +218,18 @@ export const trackPageScrolling = (enabled, router) => {
     100: [],
   };
   const scrollListener = () => {
+    const currentPath = normalizeTrackingUrl(router.route.path);
     Object.keys(scrollTargets).forEach((target) => {
       if (
-        getScrollPercent() >= parseInt(target) &&
-        !scrollTargets[target].includes(router.route.path)
+        getScrollPercent() >= parseInt(target, 10) &&
+        !scrollTargets[target].includes(currentPath)
       ) {
-        scrollTargets[target].push(router.route.path);
+        scrollTargets[target].push(currentPath);
         trackEvent([
           "Interaction",
           "Scroll Depth",
-          router.route.path,
-          `${target}%`,
+          currentPath,
+          parseInt(target, 10),
         ]);
       }
     });
@@ -102,19 +242,16 @@ export const trackPageScrolling = (enabled, router) => {
 };
 
 /**
- * Track user navigation from one page to another
+ * Track user navigation from one page to another with normalized URLs.
  *
- * @param enabled Boolean
+ * @param router VitePress router
  */
 export const trackRouterNavigation = (router) => {
   const trackNavigation = () => {
-    if (!document.cookie.includes("mtm_cookie_consent")) {
-      return;
-    }
-    _paq.push(["setCustomUrl", router.route.path]);
-    _paq.push(["setDocumentTitle", router.route.data.title]);
-    _paq.push(["trackPageView"]);
-    _paq.push(["enableLinkTracking"]);
+    trackPageView({
+      path: router.route.path,
+      title: router.route.data?.title,
+    });
   };
   watch(() => router.route.data.relativePath, trackNavigation, {
     immediate: true,