Hugo: Redirect 301 Layout – Script Everything

If you’ve created a static site using the wonderful Hugo package and need to create some simple redirect HTML web pages then you’ll need to do the following:

Create your HTML template and place it in your main layout folder.
Create an archetype template file.
Create a file using the archetype and fill in all the meta header information.
Publish your page.

Creating a simple redirect layout in Hugo is relatively easy and can help if you are transitioning from other content providers such as WordPress where your Hugo website structure may slightly change for some posts and pages.

Let’s explore these steps in a little more detail:

1. Create HTML Template

To create a redirecting HTML page we need to create a new HTML file and folder in Hugo.

As we are creating one page to represent one redirect, we will name the file single.html and place it in a new folder which we will label redirect .

When you have done this your folder structure should look something like this:

hugo_root/
  ├── archetypes/
  │   └── default.md
  ├── content/
  │   └── posts/
  │       └── my-blog-posts.md
  ├── layouts/
  │   └── redirect/         <--- CREATE THIS FOLDER
  │       └── single.html    <--- AND CREATE THIS FILE
  ...

Barebones HTML Redirect File

The contents of the newly created single.html file should be as follows:

<!DOCTYPE html>
<html lang="{{ .Site.Language.Lang }}">
<head>
    <meta http-equiv="Refresh" content="0; url='{{ .Params.redirect }}'" />
</head>
<body></body>
</html>

Barebones with Google Analytics

<!DOCTYPE html>
<html lang="{{ .Site.Language.Lang }}">
<head>
    {{ template "_internal/google_analytics_async.html" . }}
    <meta http-equiv="Refresh" content="0; url='{{ .Params.redirect }}'" />
</head>
<body></body>
</html>

Barebones with Link in Body

<!DOCTYPE html>
<html lang="{{ .Site.Language.Lang }}">
<head>
    {{ template "_internal/google_analytics_async.html" . }}
    <meta http-equiv="Refresh" content="0; url='{{ .Params.redirect }}'" />
</head>
<body>
<!-- uncomment if you want to insert your template's header {{ partial "header.html" }} -->
<p>Please click this [link]({{ .Params.redirect }}) if you are not redirected.</p>
<!-- uncomment if you want to insert your template's footer any {{ partial "footer.html" }} -->
</body>
</html>

2. Create Archetype Template File

To make it easier for us to remember the content needed in a redirect post we will create an archetype template file with all the needed data.

Therefore, in your archetype folder create a file labelled redirect.md – this must be the same name as the folder created in layouts in the previous step.

Your folder structure for your site should look something like this:

hugo_root/
  ├── archetypes/
  │   ├── redirect.md      <--- CREATE THIS FILE
  │   └── default.md
  ├── content/
  │   └── posts/
  │       └── my-blog-posts.md
  ├── layouts/
  │   └── redirect/
  │       └── single.html
  ...

Archetype Template

Then within this file populate the contents like so:

+++
draft = true
date = {{ .Date }}
type = "redirect"
slug = "{{ .Name }}"
redirect = "https://..."
+++
CONTENT NOT RENDERED

Only insert details here if you want to enter any additional detail about the purpose of the redirect, otherwise you can just leave this portion of your file blank.

There are several important things here to note:

There needs to be a type meta tag which matches the name of the layout folder we just created.
The content are of the markdown post isn’t rendered, therefore you can type whatever you want in here. Maybe even an explanation on what to do in case you forget!
Remember when you’re ready to flick this redirect live change the draft from true to false or remove the draft line completely.

3. Create Redirect Page

To create a redirect page we open up our terminal, in our current Hugo website working directory and enter the command:

$ hugo new redirect/test-my-redirect.md

This should create a new file in your contents folder, such that your directory now looks like this:

hugo_root/
  ├── archetypes/
  │   ├── redirect.md
  │   └── default.md
  ├── content/
  │   ├── redirect/
  │   │   └── test-my-redirect.md   <--- HELLO WORLD!! =)
  │   └── posts/
  │       └── my-blog-posts.md
  ├── layouts/
  │   └── redirect/
  │       └── single.html
  ...

Upon opening this new file you should see something like the following:

+++
draft = true
date = 2020-05-27T16:26:14+10:00
type = "redirects"
slug = "test-my-redirect"
redirect = "https://..."
+++
CONTENT NOT RENDERED

Only insert details here if you want to enter any additional detail about the purpose of the redirect, otherwise you can just leave it blank.

From here you can edit this file where needed, especially the redirect tag and then remove the draft tag when finished.

4. Publish

Check your redirect file is working first by loading up the hugo local server:

$ hugo server

Test the link by visiting the url: localhost/test-my-redirect

If all works well you should hopefully experience the redirect!

Conclusion

In this article we were able to learn in Hugo:

How to create a custom template layout.
How to create an archetype to help use the layout needed for this type of layout template.
How to create a new page using the archetype and its corresponding layout.
How to publish our new layout and test.

Hopefully your redirect issues in Hugo will be solved with this helpful post.