How to set up Google Analytics with Hugo



This article shows how to set up Google Analytics for your Hugo website in minutes.

Step 1: Google Analytics tracking code

Start by heading over to https://analytics.google.com and get your tracking code.
If you have not yet signed to Google Analytics, just follow the instructions to link your Google account and register a new site.

Once that is done, navigate to your websites analytics page, and copy the tracking code.
The format of the code is UA-\d{9}-1 and it will look something like this:

Picture of a tracking ID

NOTE: The Google Analytics UI is subject to change, but at the time of writing the code can be found under:

admin > yourwebsite > Tracking Code


Step 2: Add the code to your site

In order to make Google Analytics track your page, you need to place the code into the <head> section of your website and make Hugo process it.

Method 1 - Using Hugo's internal template

Hugo provides an internal template that you can use to automatically process the code. First add the tracking code to your sites main configuration file as a top level variable:

googleAnalytics = "UA-999999999-1"

NOTE: Some themes include a blank googleAnalytics variable in the configuration file. Make sure to only have one occurance of this variable in the configuration file.

Next you need to add the internal template to your sites <head> section.
If you are using a theme, the <head> section is almost certainly generated by a partial. For example, my theme has a partial called meta.html that generates the section.
If you are unsure where to find the section, consult your themes README file, or try using utilities such as grep or your editors search funtionality.

Once you have located the <head> section of your site, go ahead and add this line to it:

{{ template "_internal/google_analytics.html" . }}

This internal template will automatically acquire the tracking code from your site parameters, and process it accordingly. This is the recommended way to add Google Analytics on your page, and should be used when possible.

Method 2 - Using a partial

Another way to add the Analytics is to add the Global site tag (gtag for short) to a partial, and linking that partial to your sites <head> section.

Start by navigating to your websites Google Analytics tracking page (the same page you probably got the code from) and copying the gtag script.

It should look something like this:

<!-- Global site tag (gtag.js) - Google Analytics -->
<script async src="https://www.googletagmanager.com/gtag/js?id=UA-132076856-1"></script>
<script>
  window.dataLayer = window.dataLayer || [];
  function gtag(){dataLayer.push(arguments);}
  gtag('js', new Date());

  gtag('config', 'UA-999999999-1');
</script>

After acquiring this code, create a new partial and paste the code into it. Remember that the partial needs to be a valid html file to work.
For example: google-analytics.html

Now simply add that partial to your <head> section like this:

{{ partial "google-analytics" . }}


Step 3: Test the configuration

Before you deploy the new configuration, you probably want to make sure it works as intended.

The easiest way to do this in my opinion is to spin up a local Hugo development server and clicking around, and verify that the generated traffic is collected by Google Analytics.

Run local Hugo development server:

cd project/root/directory/
hugo serve -D

Navigate to whatever localhost port the server started in (1313 bt default) and click around to generate some traffic to be sent to Google Analytics.

Now open the Google Analytics dashboard for your website, and look for a field that says something like “Active users right now”

Google Analytics active users field

If the field reports at least one active user (you clicking around on the development server) then congratulations, you have enabled Google Analytics on your Hugo site!



Troubleshooting

If Google Analytics in not picking up your site's traffic, make sure you are not affected by any of these issues:

Privacy software

If you are using software that blocks trackers/scripts (Ublock, Ghostery, NoScript, etc.) your traffic will obviously not be logged by Google Analytics, because the script will get blocked.

How to fix:
Disable any such software, or use an incognito window.

Make sure the script is placed in the right place

If the script is not inside the <head> section, it will not get executed and no traffic will get logged.

How to fix:
Open your browsers development tools, and make sure the script gets loaded and executed correctly:

Network tab showing http 200 for tracking script - chrome

If you see your script in either network tab or in the DOM, verify that you have placed either the internal template or gtag partial in the right place.