How to add analytics to a Hugo site: where the script tag goes
Hugo writes plain HTML, so analytics is one tag in the head. Which template writes that head, how to use a theme's slot or override its file without touching themes/, and how to keep hugo server out of the numbers.
In this article
- 1What you're adding: one script tag
- 2Find the template that writes the head
- 3Look for the theme's own slot first
- 4Put the tag in a partial of its own
- 5No slot? Override the theme's file
- 6Keep hugo server out of your numbers
- 7Hugo's built-in Google Analytics template
- 8Build, then check the output
- 9A short checklist
Hugo builds plain HTML files, so analytics on a Hugo site is one script tag in the <head> of every page. The work is finding the template that writes that head, and adding the tag in a way the next theme update won't undo.
This guide covers where the tag goes in your own layouts and in a theme, how to keep hugo server previews out of your numbers, and how to check the built site before it goes live. It works for any analytics tool that installs with a script tag. The Hugo details follow its own documentation, as of November 2026.
What you're adding: one script tag
Most analytics tools give you a snippet shaped roughly like this:
<script defer src="https://analytics.example.com/script.js" data-site="YOUR-SITE-ID"></script>That's a placeholder, not a working tag. Copy the exact one from your tool, because the address and attributes differ from tool to tool, and follow its placement instructions if it has any. If your Hugo site is published on GitHub Pages, the hosting side is covered in the GitHub Pages guide. This one is about the Hugo templates.
Find the template that writes the head
Most Hugo sites wrap every page in a base template, baseof.html. Where it lives depends on the layout structure the project or theme uses:
| Structure | Base template | Partials folder |
|---|---|---|
| Hugo 0.146 and later | layouts/baseof.html | layouts/_partials/ |
| Before Hugo 0.146 | layouts/_default/baseof.html | layouts/partials/ |
Hugo 0.146 reorganised the layouts folder, and current versions still read the older paths, so a project or theme in either structure works. Open the base template and look for <head>. Many themes keep the head in a partial instead, called with a line like {{ partial "head.html" . }}, and the head is then in that file.
If the file isn't in your project's layouts folder, it comes from the theme, in themes/<theme-name>/layouts/. A theme added as a Hugo Module usually isn't in your repository at all, so read its files in the theme's own repository.
Look for the theme's own slot first
Several popular themes leave a partial inside the head that outputs nothing by default, for exactly this. You create a file with the same name in your project, and the theme picks it up. Two popular ones, as of November 2026:
| Theme | File to create in your project | Where it ends up |
|---|---|---|
| PaperMod | layouts/_partials/extend_head.html | Inside <head> on every page. The theme's own comment in the file names web analytics as a use |
| Ananke | layouts/_partials/head-additions.html | At the end of <head>. Ananke calls it the injection point for extra head code, and also offers a head-end hook if you'd rather not override the file |
For another theme, search its README and its head partial for words like “extend”, “custom” or “hook” before you copy any layout. A slot means the theme keeps its own head file, so you still get its fixes when you update it.
Put the tag in a partial of its own
Whichever file ends up loading it, keep the tag itself in a partial of its own, so there's one place to change or remove it later. Create layouts/_partials/analytics.html (or layouts/partials/analytics.html in an older project) and paste the tag into it, unchanged. Then call it just above </head> in your base template, or at the end of your head partial, which often has no </head> of its own because the base template wraps it:
{{ partial "analytics.html" . }}
</head>{{ partial "analytics.html" . }}The Hugo team's migration notes say calls to the partial function don't change with the new structure, so the same line works in both. If you're using a theme's slot, the slot file holds just this line.
No slot? Override the theme's file
Don't edit the files inside themes/. A theme update replaces them, and your tag goes with them. Hugo's template lookup rules offer a better route: when your project and a theme have a template with the same name, Hugo uses the project's.
- Copy the theme's file, for example
themes/<theme-name>/layouts/_partials/head.html, to the same path under your project'slayoutsfolder. - Copy the whole file, not only the part around
</head>. Anything you leave out disappears from every page. - Add the partial call at the end of your copy, or just above the closing head tag if the file has one.
The trade-off: when the theme later changes that file, your copy doesn't get the change. Compare the two whenever you update the theme.
Keep hugo server out of your numbers
hugo server runs while you write. If the tag loads there, your own previews can count as visits, unless your tool ignores localhost. Hugo knows which environment it's building for, so wrap the call:
{{ if hugo.IsProduction }}
{{ partial "analytics.html" . }}
{{ end }}According to Hugo's docs, hugo server builds for development unless you set an environment, and hugo (or hugo build) builds for production, so the tag only reaches the built site. A deploy that runs with --environment staging, or sets HUGO_ENVIRONMENT to anything other than production, isn't production either, and the tag is left out there. If you want it on a staging build too, check hugo.Environment, which returns the environment's name.
Hugo's built-in Google Analytics template
Hugo ships an embedded partial for Google Analytics 4. You set the measurement ID in the site config, and a template calls {{ partial "google_analytics.html" . }}. Many themes already make that call.
[services.googleAnalytics]
id = 'G-MEASUREMENT_ID'Current versions only print the tag for a GA4 ID. An old UA- ID gets a warning in the build log instead, since Google stopped processing standard Universal Analytics properties in July 2023. It works, and it's what most Hugo guides show. Google Analytics recognises returning visitors with first-party cookies such as _ga, though, and in the EU that kind of cookie generally needs the visitor's consent. Whether you can then drop a banner is the subject of what it takes to run a website without a cookie banner.
If you switch tools, take the ID out of the config as well as adding the new tag, or both keep running.
Build, then check the output
A Hugo site can be checked before it's deployed, because the output is only files.
- Build and search the output. Run
hugo --cleanDestinationDir, which also removes stale files frompublic/, then list every page that doesn't contain the script's address. Swap in your own tool's domain:
grep -rL --include="*.html" "analytics.example.com" public/A few files on that list are expected. Hugo's redirect pages for aliases have a short head of their own and send the visitor straight on, so the visit is counted on the page they land on. HTML files you keep in static/, such as a search engine's verification file, are expected too, because Hugo copies them as they are. Any other page on the list uses a template that doesn't call your partial.
- Deploy, then view the live source. Open the published site and search the page source for the script's address.
- Open the Network tab in the browser's developer tools, reload and filter by the tool's domain. You should see the script load, and usually a second request that sends the pageview. If your host sends a Content Security Policy, the tool's domain needs to be in
script-srcandconnect-src, or both are blocked. - Open the tool's live or real-time view with ad blockers off, and look for your visit.
- Check more than the home page. A post, a list page and the 404 page can each use a different template.
If the tag is missing everywhere after deploy, look at the build command first. A build that isn't production leaves out anything inside hugo.IsProduction. Blockers matter beyond the test, too: a visitor whose blocker stops your tool's script isn't counted at all, which is one reason no two analytics tools agree on your traffic.
A short checklist
- Find the template with
<head>:baseof.htmlor a head partial, in your project or the theme. - Use the theme's head slot if it has one.
- Keep the tag in
analytics.htmland call it once, at the end of the head. - Override a theme file by copying all of it to the same path, never by editing
themes/. - Wrap the call in
hugo.IsProduction. - Search
public/for pages without the tag, then check the live site.
Lomen is one of the script-tag tools this guide is written for. Its tag carries defer, your data-site-id and the script address https://lomenanalytics.com/api/public/track.js, with no API key, package or build step, so on Hugo it goes in the analytics partial above. With a Content Security Policy, allow https://lomenanalytics.com in both script-src and connect-src. Pageviews only count from the domain you added and its subdomains, so previews from hugo server on localhost stay out of the numbers even without the hugo.IsProduction check. It sets no cookies, IP addresses are never stored, and by default nothing is kept in the visitor's browser. It doesn't track custom events or funnels, so if you need those, a broader tool is the better fit. Lomen is free during the public beta.