From d798792643b58b106f2ce1a0ffbfc78644814c74 Mon Sep 17 00:00:00 2001
From: Marco Walz <marco.walz@dfinity.org>
Date: Thu, 26 Mar 2026 16:59:37 +0100
Subject: [PATCH 1/3] feat(docs): add Matomo analytics to documentation site

Add Matomo tracking to the docs site, matching the portal's setup
(cookies disabled, link tracking enabled, same Matomo Cloud instance).

The tracking script is deployed as a single root-level file (`/matomo.js`)
rather than baked into each versioned build, so the site ID can be
updated without rebuilding existing versions.

> **TODO**: Replace `CHANGEME` in `docs-site/matomo.js` with the actual
> Matomo site ID once IT creates the site for `cli.internetcomputer.org`.
---
 .github/workflows/docs.yml |  3 +++
 docs-site/astro.config.mjs |  6 ++++++
 docs-site/matomo.js        | 15 +++++++++++++++
 3 files changed, 24 insertions(+)
 create mode 100644 docs-site/matomo.js

diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
index bc95050a..617e077d 100644
--- a/.github/workflows/docs.yml
+++ b/.github/workflows/docs.yml
@@ -88,6 +88,9 @@ jobs:
           # Copy custom domain file
           cp docs-site/public/.well-known/ic-domains root/.well-known/ic-domains
 
+          # Copy Matomo analytics script (site ID defined once here, not per-version)
+          cp docs-site/matomo.js root/matomo.js
+
           # Extract the latest version from versions.json
           LATEST_VERSION=$(jq -r ".versions[] | select(.latest == true) | .version" docs-site/versions.json)
 
diff --git a/docs-site/astro.config.mjs b/docs-site/astro.config.mjs
index 3f0c47d9..43dfea45 100644
--- a/docs-site/astro.config.mjs
+++ b/docs-site/astro.config.mjs
@@ -52,6 +52,12 @@ export default defineConfig({
             });
           `,
         },
+        // Matomo analytics — loaded from root so the site ID is defined once,
+        // not baked into each versioned build
+        {
+          tag: 'script',
+          attrs: { src: '/matomo.js', async: true },
+        },
       ],
       social: [
         { icon: 'github', label: 'GitHub', href: 'https://github.com/dfinity/icp-cli' },
diff --git a/docs-site/matomo.js b/docs-site/matomo.js
new file mode 100644
index 00000000..89f0b1ab
--- /dev/null
+++ b/docs-site/matomo.js
@@ -0,0 +1,15 @@
+var _paq = (window._paq = window._paq || []);
+_paq.push(["disableCookies"]);
+_paq.push(["enableLinkTracking"]);
+_paq.push(["trackPageView"]);
+(function () {
+  var u = "https://internetcomputer.matomo.cloud/";
+  _paq.push(["setTrackerUrl", u + "matomo.php"]);
+  _paq.push(["setSiteId", "CHANGEME"]);
+  var d = document,
+    g = d.createElement("script"),
+    s = d.getElementsByTagName("script")[0];
+  g.async = true;
+  g.src = "//cdn.matomo.cloud/internetcomputer.matomo.cloud/matomo.js";
+  s.parentNode.insertBefore(g, s);
+})();

From ca4a0035c1431dc77e27bfc02d36df8f4ace131a Mon Sep 17 00:00:00 2001
From: Marco Walz <marco.walz@dfinity.org>
Date: Thu, 26 Mar 2026 17:30:59 +0100
Subject: [PATCH 2/3] chore(docs): set Matomo site ID to 21

---
 docs-site/matomo.js | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/docs-site/matomo.js b/docs-site/matomo.js
index 89f0b1ab..77a0156c 100644
--- a/docs-site/matomo.js
+++ b/docs-site/matomo.js
@@ -5,11 +5,11 @@ _paq.push(["trackPageView"]);
 (function () {
   var u = "https://internetcomputer.matomo.cloud/";
   _paq.push(["setTrackerUrl", u + "matomo.php"]);
-  _paq.push(["setSiteId", "CHANGEME"]);
+  _paq.push(["setSiteId", "21"]);
   var d = document,
     g = d.createElement("script"),
     s = d.getElementsByTagName("script")[0];
   g.async = true;
-  g.src = "//cdn.matomo.cloud/internetcomputer.matomo.cloud/matomo.js";
+  g.src = "https://cdn.matomo.cloud/internetcomputer.matomo.cloud/matomo.js";
   s.parentNode.insertBefore(g, s);
 })();

From 105910533272962d062f7021692542b068ee6ea9 Mon Sep 17 00:00:00 2001
From: Marco Walz <marco.walz@dfinity.org>
Date: Thu, 26 Mar 2026 17:53:44 +0100
Subject: [PATCH 3/3] chore(docs): add cache headers for matomo.js

---
 docs-site/.ic-assets.json5 | 7 +++++++
 1 file changed, 7 insertions(+)

diff --git a/docs-site/.ic-assets.json5 b/docs-site/.ic-assets.json5
index a630eef6..f35b23d6 100644
--- a/docs-site/.ic-assets.json5
+++ b/docs-site/.ic-assets.json5
@@ -33,5 +33,12 @@
     "headers": {
       "Cache-Control": "public, max-age=60"
     }
+  },
+  {
+    // Matomo analytics — short cache so site ID changes are picked up quickly
+    "match": "matomo.js",
+    "headers": {
+      "Cache-Control": "public, max-age=300"
+    }
   }
 ]