SEO for Hugo websites

This tutorial will show you how to improve the SEO of your Hugo site. Let’s get started!

Ron Erdos
Updated March 7, 2022
Tested with Hugo version 0.93.2

SEO titles & meta descriptions

Before we delve into how to optimise these in Hugo, let’s take a quick look at what these fields are, where they show up, and what they do.

SEO titles and SEO descriptions in Hugo: How to generate them

Before we get into the specifics, I want to be clear that the approach shown below is for “old-school” blog homepages which display, say, the ten most recent posts, and then paginates.

However, if you are using a “marketing-style” blog homepage (which asks for the user’s email address and does not display any blog posts), then you’ll need to tweak the code in this section. That said, you’ll probably still find a lot of it useful.

Onwards!

Broadly, the code I’ll show you in just a bit produces three SEO outcomes:

Populate the homepage SEO title and homepage meta description from the Hugo config file, config.toml.
Where the homepage spills over onto page 2, page 3 etc, also populate the SEO title and meta description for these pages from the Hugo config file, config.toml, but append | Page 2 (or whatever number is appropriate) to the SEO <title>.
For example, if your site’s homepage SEO <title> is ABC Widgets, then the SEO <title> for the second pagination of the homepage would be ABC Widgets | Page 2.
This ensures each page has a unique SEO title and unique meta description, which Google likes because it helps it to categorise and understand web pages.
For blog posts and pages, populate the SEO title from the YAML front matter if it exists (with a key I’ve called seoTitle). If this field seoTitle does not exist, populate the SEO title with the traditional headline (which usually appears in the <h1> headline). This field is named title.
Populate the meta description for blog posts and pages from the YAML description field. If this field is missing or it is not filled out, the meta description will be an empty string "".

Code for playing along

Here’s the relevant Hugo SEO code I use in my <head> section:

{{ $paginator := .Paginate (where .Site.RegularPages ".Params.post" "!=" false) }}

{{ if .IsHome }}
	{{ if eq $paginator.PageNumber 1 }}
		<title>{{ .Title }}</title>
		<meta name="description" content="{{ .Site.Params.description }}" />
	{{ else }}
		<title>{{ .Title }} | Page {{ $paginator.PageNumber }}</title>
		<meta name="description" content="This is page {{ $paginator.PageNumber }} of our content." />
	{{ end }}
{{ else }}
	{{ if .Params.seoTitle }}
		<title>{{ .Params.seoTitle }}</title>
	{{ else }}
		<title>{{ .Title }}</title>
	{{ end }}
	<meta name="description" content="{{ .Description }}" />
{{ end}}

Code walkthrough

Okay, that’s a lot of code to walk through! Bear with me, and let’s walk through it, line by line.

{{ $paginator := .Paginate (where .Site.RegularPages ".Params.post" "!=" false) }} This is where we set up the paginator object. You need to declare this here, even if you’ve declared it elsewhere in your Hugo site. The where statement I’ve used in my paginator object helps allow me to have subfolderless urls (of the form example.com/my-blog-post). For more on this, see my article on subfolderless urls in Hugo.

{{ if .IsHome }} This is an “if statement” which checks to see if the page is the homepage.

{{ if eq $paginator.PageNumber 1 }} This sets us up to produce SEO Outcome 1, as described above. We’re checking if the current page is equal to (eq) the pure version of the homepage, such as example.com/.

<title>{{ .Title }}</title> This populates the SEO <title> of the homepage with the site title from our configuration file, config.toml.

<meta name="description" content="{{ .Site.Params.description }}" /> Similarly, this populates the homepage’s SEO description from config.toml.

{{ else }} Now we move on to Page 2, Page 3 etc of the homepage (SEO Outcome 2, as above).

<title>{{ .Title }} | Page {{ $paginator.PageNumber }}</title> For these pages, we want the same SEO <title> as for the “pure” homepage, just with the page number appended so that it is unique. For example, if your site’s homepage SEO <title> is ABC Widgets, then Page 2’s title would be ABC Widgets | Page 2.

<meta name="description" content="This is page {{ $paginator.PageNumber }} of our content." /> Here we make our SEO description unique for each of these paginated pages. For example, Page 2 would have this SEO description: “This is page 2 of our content”. Of course, you could write a better SEO description than this, but you get the idea.

{{ end }} Here we end the code block we started at {{ if eq $paginator.PageNumber 1 }}

{{ else }} Now we start on SEO Outcome 3 (see above). We’re doing the SEO <title>s and descriptions for blog posts and pages (technically, anything which isn’t the homepage).

{{ if .Params.seoTitle }} If an seoTitle parameter has been set in the YAML front matter of the post …

<title>{{ .Params.seoTitle }}</title> … then use it as the SEO <title>.

{{ else }} However, if one hasn’t been written …

<title>{{ .Title }}</title> … then the fallback is to make the <h1> title serve double-duty as the SEO <title>.

{{ end }} That wraps up SEO <title>s …

<meta name="description" content="{{ .Description }}" /> Either way, with or without a custom SEO <title> in the YAML front matter, use the YAML description field to populate the SEO description.

{{ end}} We’re done here!

Do we really need to make each SEO title and SEO description unique?

Above, I mentioned that we should make the SEO <title> and SEO description of each page unique, to keep Google happy.

I want to cover this a bit more, for the interested. Feel free to scroll down otherwise!

Out of the box, Hugo’s pagination delivers a slightly sub-optimal SEO experience.

If you have paginated list content, such as on your homepage or in your sections, then you will end up with urls like this:

/
/page/2
/page/3

All well and good.

The slight SEO issue is that each of those pages will have the same document <title> and meta description, which is something Google cautions against:

Avoid repeated or boilerplate titles. It’s important to have distinct, descriptive titles for each page on your site.

However, one could argue this doesn’t apply to paginated pages.

In March of 2018, John Mueller, a Webmaster Trends Analyst at Google, was asked:

John, do you agree that people can safely ignore the duplicate meta description warning in Google Search Console for paginated archive URLs?

In other words, is this Hugo pagination issue a problem for SEO?

John replied:

Yep, that’s fine [to ignore the relevant Google Search Console warning].
It’s useful to get feedback on duplicate titles & descriptions if you accidentally use them on totally separate pages, but for paginated series, it’s kinda normal & expected to use the same.

Okay, so it may not be a problem for Google; however I believe the best way to control how Google treats your on-page content is to exercise careful governance over what you publish. And my code above does exactly that.

Canonicals

I like to include what’s called a “self-referential canonical” on each page of my sites.

Let me explain this whole kit and caboodle below.

What is a canonical link?

A canonical link is a way to tell Google that the page it’s currently crawling actually has an “official” version at a different url.

For instance, example.com/life-on-mars/?tracking=123 might have a canonical url of example.com/life-on-mars/.

Canonicals go in the <head> section of a web page, and have the form: <link rel="canonical" href="https://example.com/life-on-mars/" />

Canonicals can also live in HTTP headers (which is useful for non-HTML documents such as PDFs), and have the form: Link: <http://www.example.com/downloads/return-to-the-moon.pdf>; rel="canonical"

Canonicals are one way to clean up duplicate content on your site, however, Google considers them a “strong hint”, rather than a directive. This means they can be (and frequently are) ignored by Google.

Canonicals: Code for sites without pagination

If you don’t have pagination on your Hugo site, then the code for canonicals is pretty straightforward.

Here’s the Hugo code for inserting a self-referential canonical into the layout file that generates the <head> section:

<link rel="canonical" href="{{ .Permalink }}" />

Code walkthrough

The {{ .Permalink }} variable in the line of code above ensures that you’ll get a self-referential canonical on every page of your Hugo site, be it homepage, blog post, page, index and so on.

Canonicals: Code for sites that have paginated homepages

However, if you have a paginated homepage, then the code below will work better:

{{ $paginator := .Paginate (where .Site.RegularPages ".Params.post" "!=" false) }}
<!-- Remove the line above if you already have it in the file, you don't need it twice in the same file (you do need it once in each file that refers to the paginator object though). -->
{{ if .IsHome }}
  {{ if eq $paginator.PageNumber 1 }}
    <link rel="canonical" href="{{ .Permalink }}" />
  {{ else }}
    <link rel="canonical" href="{{ .Permalink }}page/{{ $paginator.PageNumber }}/" />
  {{ end }}
{{ else }}
  <link rel="canonical" href="{{ .Permalink }}" />
{{ end }}

Code walkthrough

The code above generates canonical links.

First things first; we’ll need the line creating the $paginator object somewhere in this file (which for me is /layouts/partials/header.html). It’s not sufficient to create the $paginator object in another file (such as in your homepage template) in your Hugo project; it needs to be in this file too. However, if you’ve already created it in this file (as I did when I set up my SEO <title>s above), there’s no need to include it twice in the one file.

OK, moving on to the if/else statement.

First, we check if the page is the homepage, with {{ if .IsHome }}.

Next, we check if the page is the pure homepage, i.e. not a paginated “Homepage page 2” or similar. We run this check with {{ if eq $paginator.PageNumber 1 }}. Remember that eq is used instead of =, and that the word order is different to most programming languages. Anyway, if it is in fact the pure homepage, then we generate a simple, self-referential canonical link with <link rel="canonical" href="{{ .Permalink }}" />.

However, if the page is the homepage but page 2 or onwards, then we set up our canonical links to include the page number so that they are truly self-referential. We do this with an else statement and then this line: <link rel="canonical" href="{{ .Permalink }}page/{{ $paginator.PageNumber }}/" />

For example, a Hugo “Homepage page 2” would generally have a url of the form https://example.com/page/2. The canonical code discussed in this paragraph gives that page a truly self-referential canonical that matches that url exactly.

Finally, if the page is not the homepage at all—such as a blog post or a contact page—then we can use a simple canonical link generator to create accurate self-referential canonicals. We use our trusty {{ .Permalink }} to create the canonical link: <link rel="canonical" href="{{ .Permalink }}" />.

OK, so there’s a fair bit going on here, but it’s actually simpler than it looks at first glance—I promise.

A minor SEO issue: the 404 page

I cover this here: Minor SEO issue with 404 page in Hugo.