Configure Umami Analytics for Hugo

#hugo #hugo hextra theme #umami

17 February 2025

Umami is similar to Google Analytics. But it is better. Learn how to setup and use it with your hugo static website.

What is Umami?

Umami is similar to Google analytics
Umami never collects any personal information from your visitors so it is fully compliant with GDPR and CCPA
you do not need any cookie banners
you can use a paid cloud service or even selfhost umami

Add Umami to hugo

get umami hugo module

you can use umami via a hugo module
hugomod instructions
- github repo: hugomods/umami-analytics

add the module to you hugo configuration file (e. g. hugo.yaml)

module:
  imports:
  - path: github.com/hugomods/umami-analytics

run the following command to download the hugo module (go module)
```
hugo mod get -u
```

Add umami script to head of your website

add the following content in the head section of your theme (without any <head></head> parts):
```
{{ partialCached "hugomods/umami-analytics/index" . .Params.analyze }}
```
this will add a partial which adds the tracking code into your html headers

Examples: Edit head via layouts/partials

you can add the umami script to the head of your website via a partials code block
the way you can add this depends on your hugo theme

PaperMod

for PapeMod theme you can add a file called extend_head.html here
```
layouts/partials/extend_head.html
```

hextra

for hextra theme you can add a file called extend_head.html here
```
layouts/partials/custom/head-end.html
```

Add umami to hugo configuration

get website id

get the website id when viewing your website in umami and editing the website settings

Add id to configuration

Option 1: direct configuration

add the following entry in your hugo.yaml configuration

params:
  services:
    umamni_analytics:
    id: <your_website_id>

Option 2: use environment variable

you can configure the website id via an environment variable
the you do not have to add anything in you hugo configuration
remove the website id from your hugo.yaml
- then by default (without configured environment variable) there won’t be any tracking
you need to use some advanced naming convention tricks because the configuration uses snake_cased variable names and the id is not a direct param but inside the umami_analytics yaml map.
- hugo docs about using envrionment variables with special seperators

set your umami id via the following environment variable:

HUGOxPARAMSxSERVICESxUMAMI_ANALYTICSxiD="<your_website_id>"

you can run the development server like this:

HUGOxPARAMSxSERVICESxUMAMI_ANALYTICSxiD="<your_website_id>" hugo server --buildDrafts

Tips

Use environment variable as described above

this way you can disable umami by just not setting the environment variable
you can change website id easily for different modes

Local development vs. production site mode

I created two entries for my website:
- normal one
- and local development one (with localhost as domain)
then you will/can track you site visits while developing with a different website id

Change website id in hugo config

Host static website via AWS CloudFront Switching to hugo theme hextra