feat(analytics): add Umami and Matomo (#784)

exampleSite/content/docs/guide/configuration.md

@@ -394,6 +394,45 @@ To exclude an entire directory, use the [`cascade`](https://gohugo.io/configurat
 > To block search crawlers, you can make a [`robots.txt` template](https://gohugo.io/templates/robots/).
 > However, `robots.txt` instructions do not necessarily keep a page out of Google search results.
 
+### Umami Analytics
+
+To enable [Umami](https://umami.is/docs/), set `params.analytics.umami.serverURL` and `params.analytics.umami.websiteID` flag in `hugo.yaml`:
+
+```yaml {filename="hugo.yaml"}
+params:
+  analytics:
+    umami:
+      serverURL: "https://example.com"
+      websiteID: "94db1cb1-74f4-4a40-ad6c-962362670409"
+      # scriptName: "umami.js" # optional (default: umami.js)
+      # https://umami.is/docs/tracker-configuration#data-host-url
+      # hostURL: "http://stats.example.org" # optional
+      # https://umami.is/docs/tracker-configuration#data-auto-track
+      # autoTrack: "false" # optional
+      # https://umami.is/docs/tracker-configuration#data-tag
+      # domains: "example.net,example.org" # optional
+      # https://umami.is/docs/tracker-configuration#data-exclude-search
+      # tag: "umami-eu" # optional
+      # https://umami.is/docs/tracker-configuration#data-exclude-hash
+      # excludeSearch: "true" # optional
+      # https://umami.is/docs/tracker-configuration#data-do-not-track
+      # excludeHash: "true" # optional
+      # https://umami.is/docs/tracker-configuration#data-domains
+      # doNotTrack: "true" # optional
+```
+
+### Matomo Analytics
+
+To enable [Matomo](https://matomo.org/), set `params.analytics.matomo.URL` and `params.analytics.matomo.ID` flag in `hugo.yaml`:
+
+```yaml {filename="hugo.yaml"}
+params:
+  analytics:
+    matomo:
+      serverURL: "https://example.com"
+      websiteID: "94db1cb1-74f4-4a40-ad6c-962362670409"
+```
+
 ### LLMS.txt Support
 
 To enable [llms.txt](https://llmstxt.org/) output format for your site, which provides a structured text outline for [large language models](https://en.wikipedia.org/wiki/Large_language_model) and AI agents, add the `llms` output format to your site's `hugo.yaml`:

layouts/_partials/components/analytics/analytics.html

@@ -0,0 +1,19 @@
+{{- if hugo.IsProduction -}}
+
+<!-- Google Analytics -->
+{{- if .Site.Config.Services.GoogleAnalytics.ID }}
+  <link rel="preconnect" href="https://www.googletagmanager.com" crossorigin />
+  {{ partial "google-analytics.html" . -}}
+{{- end }}
+
+<!-- Umami -->
+{{- if .Site.Params.analytics.umami -}}
+  {{ partial "components/analytics/umami.html" . }}
+{{- end }}
+
+<!-- Matomo -->
+{{- if .Site.Params.analytics.matomo -}}
+  {{ partial "components/analytics/matomo.html" . }}
+{{- end }}
+
+{{- end }}

layouts/_partials/components/analytics/google-analytics.html

@@ -0,0 +1,13 @@
+{{- with site.Config.Services.GoogleAnalytics.ID }}
+<!-- Global site tag (gtag.js) - Google Analytics -->
+<script async src="https://www.googletagmanager.com/gtag/js?id={{ . }}"></script>
+<script>
+  window.dataLayer = window.dataLayer || [];
+  function gtag() {
+    dataLayer.push(arguments);
+  }
+  gtag("js", new Date());
+
+  gtag("config", "{{ . }}");
+</script>
+{{ end -}}

layouts/_partials/components/analytics/matomo.html

@@ -0,0 +1,19 @@
+{{- /*
+Matomo Analytics.
+https://developer.matomo.org/guides/tracking-javascript-guide
+*/ -}}
+
+<!-- Matomo -->
+<script type="text/javascript">
+  var _paq = window._paq = window._paq || [];
+  _paq.push(['trackPageView']);
+  _paq.push(['enableLinkTracking']);
+  (function() {
+    var u="//{{ .serverURL }}/";
+    _paq.push(['setTrackerUrl', u+'matomo.php']);
+    _paq.push(['setSiteId', {{ .websiteID }}]);
+    var d=document, g=d.createElement('script'), s=d.getElementsByTagName('script')[0];
+    g.type='text/javascript'; g.async=true; g.src=u+'matomo.js'; s.parentNode.insertBefore(g,s);
+  })();
+</script>
+<!-- End Matomo Code -->

layouts/_partials/components/analytics/umami.html

@@ -0,0 +1,57 @@
+{{- /*
+Umami Analytics
+https://umami.is/docs/tracker-configuration
+*/ -}}
+
+{{- with .Site.Params.analytics.umami -}}
+
+{{- if not .serverURL }}
+  {{- errorf "Missing Umami 'serverURL' configuration. See TODO" -}}
+{{- end -}}
+
+{{- if not .websiteID }}
+  {{- errorf "Missing Umami 'websiteID' configuration. See TODO" -}}
+{{- end -}}
+
+{{- $attributes := newScratch -}}
+
+{{- $attributes.SetInMap "umami" "src" (printf "%s/%s" .serverURL (.scriptName | default "umami.js")) -}}
+{{- $attributes.SetInMap "umami" "data-website-id" .websiteID -}}
+
+{{- if .hostURL -}}
+  {{- /* https://umami.is/docs/tracker-configuration#data-host-url */ -}}
+  {{- $attributes.SetInMap "umami" "data-host-url" .hostURL -}}
+{{- end -}}
+
+{{- if .autoTrack -}}
+  {{- /* https://umami.is/docs/tracker-configuration#data-auto-track */ -}}
+  {{- $attributes.SetInMap "umami" "data-auto-track" .autoTrack -}}
+{{- end -}}
+
+{{- if .tag -}}
+  {{- /* https://umami.is/docs/tracker-configuration#data-tag */ -}}
+  {{- $attributes.SetInMap "umami" "data-tag" .tag -}}
+{{- end -}}
+
+{{- if .excludeSearch -}}
+  {{- /* https://umami.is/docs/tracker-configuration#data-exclude-search */ -}}
+  {{- $attributes.SetInMap "umami" "data-exclude-search" .excludeSearch -}}
+{{- end -}}
+
+{{- if .excludeHash -}}
+  {{- /* https://umami.is/docs/tracker-configuration#data-exclude-hash */ -}}
+  {{- $attributes.SetInMap "umami" "data-exclude-hash" .excludeHash -}}
+{{- end -}}
+
+{{- if .doNotTrack -}}
+  {{- /* https://umami.is/docs/tracker-configuration#data-do-not-track */ -}}
+  {{- $attributes.SetInMap "umami" "data-do-not-track" .doNotTrack -}}
+{{- end -}}
+
+{{- if .domains -}}
+  {{- /* https://umami.is/docs/tracker-configuration#data-domains */ -}}
+  {{- $attributes.SetInMap "umami" "data-domains" .domains -}}
+{{- end -}}
+
+<script async defer {{ range $k, $v := ($attributes.Get "umami" ) }} {{ (printf `%s=%q` $k $v) | safeHTMLAttr }}{{- end -}}></script>
+{{- end -}}

layouts/_partials/google-analytics.html

@@ -1,13 +1,2 @@
-{{- with site.Config.Services.GoogleAnalytics.ID }}
-  <!-- Global site tag (gtag.js) - Google Analytics -->
-  <script async src="https://www.googletagmanager.com/gtag/js?id={{ . }}"></script>
-  <script>
-    window.dataLayer = window.dataLayer || [];
-    function gtag() {
-      dataLayer.push(arguments);
-    }
-    gtag("js", new Date());
-
-    gtag("config", "{{ . }}");
-  </script>
-{{ end -}}
+{{- /* Only for compatibility. */ -}}
+{{- partial "components/analytics/google-analytics.html" . -}}

layouts/_partials/head.html

@@ -53,11 +53,7 @@
     <link href="{{ $customCss.RelPermalink }}" rel="stylesheet" />
   {{- end }}
 
-  <!-- Google Analytics -->
-  {{- if and hugo.IsProduction .Site.Config.Services.GoogleAnalytics.ID }}
-    <link rel="preconnect" href="https://www.googletagmanager.com" crossorigin />
-    {{ partial "google-analytics.html" . -}}
-  {{- end }}
+  {{ partial "components/analytics/analytics.html" . }}
 
   <script>
     // The section must not be in the theme.js file because it can create a quick flash (switch between light and dark).