feat(docs): add Matomo analytics to documentation site (#469)

* 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`.

* chore(docs): set Matomo site ID to 21

* chore(docs): add cache headers for matomo.js

Author: marc0olo

.github/workflows/docs.yml

@@ -86,6 +86,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)
 

docs-site/.ic-assets.json5

@@ -0,0 +1,44 @@
+[
+  {
+    // Static assets built by Astro — content-hashed filenames, cache forever
+    "match": "**/_astro/**",
+    "headers": {
+      "Cache-Control": "public, max-age=31536000, immutable"
+    }
+  },
+  {
+    // Search index
+    "match": "**/pagefind/**",
+    "headers": {
+      "Cache-Control": "public, max-age=31536000, immutable"
+    }
+  },
+  {
+    // HTML pages — short cache so updates are visible quickly
+    "match": "**/*.html",
+    "headers": {
+      "Cache-Control": "public, max-age=300"
+    }
+  },
+  {
+    // Markdown endpoints and llms.txt — short cache so updates are visible quickly
+    "match": "**/*.{md,txt}",
+    "headers": {
+      "Cache-Control": "public, max-age=300"
+    }
+  },
+  {
+    // Version list — very short cache so version switcher sees updates quickly
+    "match": "versions.json",
+    "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"
+    }
+  }
+]

docs-site/astro.config.mjs

@@ -53,6 +53,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' },

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", "21"]);
+  var d = document,
+    g = d.createElement("script"),
+    s = d.getElementsByTagName("script")[0];
+  g.async = true;
+  g.src = "https://cdn.matomo.cloud/internetcomputer.matomo.cloud/matomo.js";
+  s.parentNode.insertBefore(g, s);
+})();