How to add analytics to a Hugo site

Hugo merges your project's layouts folder over the theme's, so you never edit the theme itself: create a file with the same name in your own layouts folder and Hugo uses yours. Hugo 0.146 renamed the partials folder to layouts/_partials/; on older versions and many themes it's layouts/partials/. Use whichever your Hugo version and theme use.

How to install VisitTrack on Hugo

1. 1

   Step 1: Copy your site id into hugo.toml

   Copy the id from VisitTrack's install step and add it to your site config. Keeping it in config means the partial works across environments and themes.

   hugo.tomlCopy

   [params.visitrack]
     siteId = "SITE_ID"

2. 2

   Step 2: Create the partial

   hugo.IsProduction is true for hugo builds (the production environment) and false for hugo server. Hugo escapes the attribute value for you.

   layouts/_partials/visitrack.htmlCopy

   {{ if hugo.IsProduction }}
     {{ with site.Params.visitrack.siteId }}
       <script defer data-site="{{ . }}" src="https://visitrack.app/tracker.js"></script>
     {{ end }}
   {{ end }}

3. 3

   Step 3: Include it in the head

   If your theme has a head hook, put the include there — PaperMod reads extend_head.html, and many themes have a similar hook (check your theme's docs). Otherwise copy the theme's head.html (or the <head> part of baseof.html) into your own layouts folder and add the line before </head>.

   layouts/_partials/extend_head.html (PaperMod)Copy

   {{ partial "visitrack.html" . }}

4. 4

   Step 4: Build and deploy

   Run hugo (or let your host build it), deploy, and open the live site.

How to check VisitTrack is working on Hugo

1. Search the generated public/index.html for tracker.js after a production build — it should be there; under hugo server it shouldn't.
2. Open the deployed site and read two posts; the VisitTrack live view shows you and the Pages tab lists both paths.
3. Your theme's 404.html usually has "404" or "not found" in its title, so broken links show up as page_not_found events automatically.

Does VisitTrack track Hugo page navigation?

Hugo output is plain static HTML, so every page is a full page load and one pageview. Taxonomy pages (/tags/go/), section lists and paginated lists (/posts/page/2/) each have their own path.

If your theme uses a client-side page-transition library that changes the URL with the History API, those navigations are counted too — no theme changes needed.

How to track custom events and goals in Hugo

Markdown links can't carry custom attributes in Hugo, so add a shortcode that renders a link with data-vt-goal and use it in your content. (Shortcodes live in layouts/_shortcodes/ on Hugo 0.146+, layouts/shortcodes/ before.)

<!-- layouts/_shortcodes/goal.html -->
<a href="{{ .Get "href" }}" data-vt-goal="{{ .Get "name" }}">{{ .Inner }}</a>

<!-- in any post -->
{{< goal href="https://app.example.com/signup" name="blog_signup_click" >}}Try it free{{< /goal >}}

To measure how many readers finish a post, add <div data-vt-scroll="post_finished"></div> near the end of your single.html template. It fires once per page when that element is half visible. Then make either event a goal in Settings → Goals.

Script options you might need on Hugo

All optional — add them to the same tag. Full reference: script configuration.

Hugo troubleshooting

Not on Hugo? See all 29 integration guides.