First draft of Matomo analytics

[petecheslock]

Here’s how the global analytics.js client module tracks pageviews and anchors reliably across the site.
NOTE: An SPA (Single Page Application) loads once and swaps content with JavaScript, so URL changes don’t reload the page. Because there are no full reloads, analytics won’t auto-record pageviews or anchor jumps—you must send them manually. Our client module does exactly that for route changes and same-page anchors, and dedupes them so each action counts once.

1. Registration in Docusaurus config

// docusaurus.config.js
clientModules: [require.resolve('./src/clientModules/analytics.js')],

• What this does: Loads the client module on every page, one time, across the entire SPA.

2. Client-side only

import ExecutionEnvironment from '@docusaurus/ExecutionEnvironment';
// ...
if (!ExecutionEnvironment.canUseDOM) return;

• Why it matters: SSR (Server-Side Rendering) renders pages on the server and ships HTML to the browser; there’s no window/document during SSR. Analytics must not run server-side (it would crash or send bogus hits), so it should initialize only in the browser after the DOM exists. That’s why we guard with ExecutionEnvironment.canUseDOM before starting Matomo.

3. Environment-aware site selection

• resolveMatomoSiteId(hostname):
  • localhost / Netlify → siteId 6
  • *llm-d.ai / .llm-d.ai → siteId 7
  • unknown hosts → analytics disabled

4. One-time Matomo initialization

• Privacy & delivery:
  • disableCookies
  • alwaysUseSendBeacon
  • enableLinkTracking
• Tracker:
  • setTrackerUrl('//analytics.ossupstream.org/matomo.php')
  • setSiteId(siteId)
  • Loads matomo.js asynchronously

5. SPA navigation tracking (Docusaurus lifecycle)

• Uses onRouteDidUpdate({ location, previousLocation }) to track:
  • setReferrerUrl (when available)
  • setCustomUrl (includes hash if present)
  • setDocumentTitle (anchor-enhanced title)
  • trackPageView
• Re-attaches anchor listeners after each route change to catch late-rendered anchors.

6. Same-page anchor tracking (virtual pageviews)

• Clicks on anchors within the same pathname:
  • Virtual pageview with pathname#hash
  • Title enhanced to Base Title - anchor
• De-duplication:
  • Remembers last virtual pageview (URL + timestamp)
  • Skips the immediate route-update track for same-page hash changes within 1.5s
  • Prevents double counting for hash navigations

7. Title stability

• getBaseTitle() trims a single trailing " - section" to avoid compounding titles across multiple anchor clicks.

8. Robustness

• Gracefully no-ops if analytics is unavailable or host is unrecognized.
• Anchor listener rebind protects against late DOM updates.
• Malformed URLs and odd edge cases do not throw or corrupt metrics.

9. Tests (Jest + jsdom)

• Cross-page navigation (no hash) tracks once with correct referrer.
• Direct load to hashed URLs enhances title and tracks once.
• Same-page anchor clicks create one virtual pageview per click.
• Cross-page anchors are handled by route update, not the same-page handler.
• Title does not compound over multiple anchor navigations.
• Late-rendered anchors receive listeners after route updates.
• Full URL anchors (absolute) resolve correctly.
• Rapid sequential clicks on different anchors aren’t double-counted.
• Malformed URLs and unavailable analytics do not crash or emit bad calls.

[netlify]

✅ Deploy Preview for elaborate-kangaroo-25e1ee ready!

Name	Link
🔨 Latest commit	de6bcc4
🔍 Latest deploy log	https://app.netlify.com/projects/elaborate-kangaroo-25e1ee/deploys/689a48685adb4f00084558ce
😎 Deploy Preview	https://deploy-preview-78--elaborate-kangaroo-25e1ee.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[petecheslock]

While i was testing this feature out, I made two other changes to clean up the footer for the social links, and added a github fork button with star count, docusaurus didn't seem to have this feature natively.

[petecheslock]

This one looks a little complex, but mostly its the challenge of capturing analytics from "single page sites". Hopefully the AI assisted PR description explains why this is, and how the code works. I've confirmed on the Matomo instance that we are only capturing anonymous page views counts, and most importantly we can see links to the anchor pages which is helpful to know where on a page folks are being directed to.

[jessicachitas]

Looks good!