Setting Up 404 Redirect for Hugo Using Azure Static App

A long time ago in a galaxy far, far away…

This post is over 12 months old and Hugo is evolving. Please be mindful of that when reading this post, young Padawan, as it could be outdated. I try to keep things up to date as much as possible. If you think something needs updating, please let me know in the comments.

Introduction

I recently realised that my blog isn’t redirecting to a 404 page when a page isn’t found. Instead it shows the default Azure Static Web App 404 page.

If I go to a page that doesn’t exist on my blog on my local machine, it redirects as expected.

By default Hugo will generate a 404 page that can be served and Hugo will do this automatically however, Azure Static Web App doesn’t serve up the 404 page by default. This post shows how to set up a 404 redirect for Hugo using Azure Static Web App.

Routes.json deprecated

When I first started looking into this, I discovered a config file you can add called routes.json that allows you to set up redirects. However, this is now deprecated and you should use staticwebapp.config.json instead.

routes.json that was previously used to configure routing is deprecated. Use staticwebapp.config.json as described in this article to configure routing and other settings for your static web app.

Setting up staticwebapp.config.json

This configuration file can be used to configure several things, but I am specifically interested in response overrides. I will just configure the 404 rule and so my config will look like this;

{
  "responseOverrides": {
    "404": {
      "rewrite": "/404.html"
    }
  }
}

This will redirect any 404 to a page called 404.html. According to the documents, this should ideally be present in the root of my site. To achieve this, I am going to save this file in my static folder. When my site is built, the contents of the static folder are pushed to the root of the site.

Setting up 404.html

With my configuration done, now I need to work on my 404 file. Hopefully, your theme has a default 404 page, if it does it will likely be found in ./themes/{theme name}/layouts/. If not, you can create one (I am not going to walk through that in this post). I am using the Clarity theme and it has a 404.html file in the layouts folder. But I am going to make some adjustments to it. So I will take a copy of that file and place it inside ./layouts. Hugo has a template lookup order that means that it will check in ./layouts first and will use that instead of the one in the themes folder. Why not just amend the one in the theme folder? Because if I update the theme, it will overwrite my changes. So here is my adjusted file;

Notice that the path is the config file is /404.html, I therefore need to make sure my 404 file has the same name.

Testing

With my new 404 file complete and config ready, I am going to raise a pull request and review the changes on the test environment that the Azure Static Web App will create. Testing this locally is only validating that the 404 file looks good, Hugo is serving the 404 file no problem, so I need to test in Azure to ensure that the webapp is picking up my staticwebapp.config.json file and serving the 404 file.

Looks good! My new config is ready to merge to main so it can be published to the live site.

Summary

I now have a nice Jedi Mind trick 404 instead of the boring Azure Static Web App default 404. This was straightforward enough to fix. If you want to read more about the staticwebapp.config.json file, check out the docs.