How to integrate MailChimp into your Hugo site cleanly

Before I worked this out, I had a bunch of Hugo partials and it was all a big mess.

Ron Erdos
Updated September 30, 2020

Section 1: Overview

From messy to DRY implementation

Allow me to to tell you the story of how I cleaned up my Hugo repo with respect to MailChimp signup forms.

Even though they all did the same thing, I had three different MailChimp signup forms on this site, because I wanted to track which page type (homepage, blog index, article) each person was on when they signed up.

I knew this was inelegant and not DRY, but I didn’t know there was another way.

Then I learned you can pass variables to MailChimp. Boom. So I consolidated my three MailChimp signup forms into one, which I put in a Hugo partial, subscribe.html. Inside this partial, I sent the page url as a variable to MailChimp. From then on, MailChimp started recording the page each person was on when they subscribed to my newsletter. As a bonus, I got to simplify my Hugo repo. I love simplifying code when I can!

What this tutorial will cover

This tutorial will show you how to add MailChimp signup page tracking to your Hugo site. I’ll cover:

how to build your MailChimp form in the MailChimp UI
how to get the raw HTML code for your form
and how to implement it on your Hugo site using a variable to tell you which page a reader was on when they signed up.

Note: This tutorial is based on this MailChimp help page but customised for implementation on Hugo websites. I’ve also chosen a shorter name for the main variable so that you can see it more easily in the MailChimp UI.

In your MailChimp admin area, head to Audience, then Signup forms, and finally Form builder.

You’ll see a WYSIWYG form designer, where you can choose from a bunch of different form fields and add them to your form by clicking on them.

Let’s say you’re just collecting email addresses, no names or other details. (I believe this will yield you more signups). Go ahead and add the Email field to the form.

Adding a hidden text field to track which page a reader was on when they filled out your form

Now we’ll need to add one more field, a Text field, which we’ll use to track which page of your site a reader was on when they signed up. Go ahead and add said Text field to your form. Your readers won’t see it; we’ll hide it (details below).

Once you’ve added the field, it’s time to configure it. Click on your newly-created text field and then on Field Settings over on the right.

Here are the three things we’ll need to configure within this area:

Set the Field label’s value to Signup URL
Set the Field tag’s value to SIGNUP
Set the Field visibilty to Hidden

How to get the MailChimp form embed code

OK, once you’ve built your form, it’s time to get the embed code.

To do this in MailChimp, you actually need to go back to the main Signup forms area and then into the Embedded forms section. It’s a little confusing, but you’re actually dealing with the same form, not a new one as I originally thought.

How to get the raw HTML form embed code

Regarding the form code itself: I personally like to use my own CSS and no JavaScript on my forms, so I opt for the raw HTML. In MailChimp, this is called Unstyled. Click on that option if you want the same thing.

Turn off the “bloat options”

On the left of the Unstyled screen, I like to uncheck the “bloat options” such as Show interest group fields and Show required field indicators and Show format options. Turn ’em all off, I say! Of course, it’s up to you.

Section 3: How to integrate your MailChimp form with your Hugo site

Now for the fun part (well, I think it’s fun, anyway)!

Creating and using a Hugo partial for your MailChimp form

First, I copy my Unstyled form code from MailChimp and paste it into a new Hugo partial. Call it something like subscribe.html. It goes, by definition, in the /layouts/partials/ folder.

To use this partial, it needs to go in a template (a file within the /layouts/ folder). If you wanted your MailChimp subscribe form at the bottom of every blog post, for example, then your single.html template (which controls your blog post layout) might look like this:

{{ partial "header.html" . }}

<h1>
	{{ .Title }}
</h1>

<div class="date">
	{{ dateFormat "Jan 2, 2006" .Date }}
</div>

{{ .Content }}

{{ partial "subscribe.html" . }}
{{ partial "footer.html" . }}

Our subscribe partial is there on the second-last line, just above the footer partial. Also please note the dot . just before the two closing curly braces of each partial—it needs to be included for reasons I won’t get into now.

Customising MailChimp form CSS

I then customise the CSS to suit my site, which I won’t go into here as every site has a different design.

Adding a page identifier to the form action using a Hugo variable

Next, I customise the form action url that I got from MailChimp. I add a tracking parameter that tells me which page a reader was on when they signed up using my MailChimp form.

The form action you get from MailChimp will have the syntax:

action="https://XXXXX.us4.list-manage.com/subscribe/post?u=XXXXXXXXXXXXXXXXXXXXXXXX&id=XXXXXXXXXX"

We’re going to take the action url MailChimp gave us and append the SIGNUP variable we created when we earlier configured the hidden Text field in the MailChimp WYSIWYG editor.

And we’re going to set the value of this SIGNUP parameter to the url of the current page; the url the reader is on.

To achieve these things, we’re going to append &SIGNUP={{ .Permalink }} to the action url, so the syntax looks like this:

action="https://XXXXX.us4.list-manage.com/subscribe/post?u=XXXXXXXXXXXXXXXXXXXXXXXX&id=XXXXXXXXXX&SIGNUP={{ .Permalink }}"

Let’s talk briefly about Hugo’s {{ .Permalink }} variable.

The Permalink variable in Hugo

The {{ .Permalink }} variable is built in to Hugo and will provide the full (absolute) url of the page the reader was on when they signed up.

One caveat: to get absolute urls, you need to specify your hostname in your Hugo config.toml, like this: baseURL = "https://example.com/"

Section 4: Viewing and analysing your MailChimp data

Once you implement the above, you can click on any new subscribers within the MailChimp admin area and see their Signup URL.

You can also segment your audience by signup url within the MailChimp All contacts screen. So in my case, for example, I’ll be able to tell how many readers subscribed from the homepage, how many from the Hugo section homepage, and how many from each article.

I haven’t used MailChimp’s segmentation yet, as I’ve only just implemented the Signup URL variable. However, I’ll update this tutorial with more details and summary stats in the future.