404 Pages

Hugo generates a bunch of URL’s when it builds our site. Hugo does this by analyzing our content folder and layouts folder.

But sometimes users will visit our site and go to a URL that does not exist. So what do we show when this happens?

Most sites show a default 404 page, 404 is the http status code used when web server cannot find something that is requested. In this case, the web server can not find a page that the browser is looking requesting.

404 Template

To display some default message for pages that are not found, create a 404.html file inside of layouts.

Your folder structure should now look like:

my-blog
├── archetypes
|   └── default.md
├── content
|   └── posts
|       └── my-first-post.md
├── data
├── layouts
|   ├── _default
|   |   ├── summary.html
|   |   ├── single.html
|   |   ├── list.html
|   |   └── baseof.html
|   ├── 404.html
|   └── index.html
├── static
├── themes
└── config.toml

Open the new file and paste the following snippet:

{{ define "main"}}
<main>
  <div>
    <h1><a href="/">Go Home</a></h1>
  </div>
</main>
{{ end }}

In our case, we will just show a page that says Go Home and if they click it - it will bring them back to our home page.

Test

You may be trying to test this right now by saving your changes and going to a path that does not exist in your browser and you may be confused why there is no Go Home message displayed.

This is because Hugo’s development server will not show this template automatically. To test if it is available, you can visit localhost:1313/404.html.

In the Optimizing section of this course, we will go over how to configure our web server to serve our 404 template automatically if no page is found.