Learn how to customise your 404 page in Hugo and avoid an edge case "soft 404"
Let’s go over some definitions before we get started.
In the intro, I mentioned I’d show you how to avoid a “soft 404” issue. I’ll cover this later on in this article; first things first.
There are two ways that I know of to generate a custom 404 page in Hugo.
The first way is to have a special template just for this purpose. It would be called
404.html and live in the root of your
When your site is generated, this would create a page called
404.html in the root of your site.
Web hosts like Netlify would see this
404.html page and automatically display it, along with the requisite
404 code, when a page can’t be found.
This option is a little more involved up front, but I think it’s cleaner in the long run.
Here’s how it works:
If it exists, delete the
404.html template in your
/layouts folder. We won’t need it, as we’ll be using a custom page instead.
Create a page in the root of your
/content/ folder called
404.md. This will become our new 404 page.
Here’s an example of what you could put inside this page:
--- title: Whoops! Page not found hidden: true layout: page --- That page can't be found. Our latest content is [on the homepage](/).
I’ll explain that
hidden custom parameter in the YAML front matter later on in this article.
In this step, when the user or Googlebot requests a url that doesn’t exist, we’re going to have Netlify show the 404 page we just created in Step 2 and also send a
404 code. Here’s how you do that:
If you don’t already have a Netlify config file (
netlify.toml) in the root of your Hugo site, create one and include this code:
[[redirects]] from = "/*" to = "/404/" status = 404
Any time a user or Googlebot requests a page that doesn’t exist, the code above will redirect them to
/404/ and correctly return a
404 response status code.
I use Netlify to host my Hugo sites (here's how to do so), and 404 pages work correctly, except for one edge case. It’s an edge case worth fixing.
An example of 404 pages working correctly: if you visit the nonsense url
/adfadfasd/ on this site, you’ll get a
404 code. Which is just as it should be.
However, the edge case is that if you visit
/404/, you get a
200 response status code.
Here’s the problem with that: it causes something called a “soft 404” error.
Now, if you’re thinking “So what? Google won’t ever find my
/404/ page”, I would say to that: don’t be so sure. They might. They have with at least one of my sites, even though I didn’t link to it from anywhere.
The best (and so far, only) way I’ve found to work around this is to block the 404 page itself from being indexed on Google.
You can do this using a
noindex tag. For the uninitiated, I explain what a noindex tag is here.
Here’s how I generate a
noindex tag for my 404 page in Hugo.
Since I use Option 2 on my own sites (including this one), I’ll walk through that scenario here.
Ensure you’ve included the
hidden: true key-value pair in the YAML front matter of your
/content/404.md page. You can see a mocked-up example of this by scrolling about halfway up this page.
Ensure you’ve included the noindex logic in the <head> section of your Hugo site as explained here.Hugo tutorials | About