How to make your WordPress 404 template editable using the block (Gutenberg) editor

When users visit a page that cannot be found on a WordPress site, they are delivered the themes 404 page template file. However, as this is not an editable page in WordPress, website owners are stuck with the content the theme author included. In this article, I show you how to make that 404 page editable using the WordPress block editor.

What is the 404 template?

If a user visits a non existent page in WordPress, they are delivered the 404.php file from the active theme. This is a template file that lives within all themes and is used when a 404 error is returned.

Most theme authors include a message in the template indicating that the page the user is trying to find cannot be found. Many also include a search form to enable to user to search the site for the content they were looking for.

However, the contents of this template are not editable from within the WordPress backend like other pages and posts. The website owner is stuck with what the theme author has decided should go on the page.

The 404.php code in the WordPress 2020 theme.
The Twenty Twenty theme has a good 404.php template example.

How to make the 404.php template content editable using the block editor

In order to make the content of this template editable there are a few steps you need to follow.

Create a new 404 page in the WordPress admin

A new page needs to be created in the WordPress admin which will be used to edit its content.

To do this we can simply navigate to Pages > Add New. Then you need to make sure that the title of the page is called “404” only. This is to make sure that we can reference the page with this title in the code later on.

Now you can add whatever content you like to this page using the WordPress block editor. This content will be rendered below the “404 not found” title when the page is served to users.

It is probably worth marking this page asĀ no-index too, so that it does not show in search results.

Modify the 404.php file in your theme

This requires editing the code in your themes 404.php file. If you are running a commercial theme then I would highly recommend that you create a child theme first before making changes to the themes template files.

In your themes 404.php file you can replace the current contents with the following.

As you can see in the code above, we firstly get the post object for the page which has the title “404“. If this returns a post object, we know that we have a page titled 404 and therefore we then get the blocks that have been added to that page using the parse_blocks() function.

We then check to see if any blocks have been added to the 404 page. If blocks are present, we create a variable to store our block output in before looping through each block and rendering each blocks output into the content variable using the render_block() function.

Some important notes to think about

It is important to note here that your sites 404 page will NOT be cached by your host. This is because when served it does not return a 200 status code and this the server does not cache its contents.

Additionally your sites 404 page is used not only for pages that don’t exist but also for requests to static files and images that may no longer exist.

Therefore there is potential for a 404 page with lots of content on to be a bottle neck for speed and using a lot of server resources. We have not really found this to be a great problem but it is something worth noting a checking.

You can mitigate some of this using a HTML fragment caching solution such as this one explained very well by Mark Jaquith.

Fragment Caching in WordPress

Thanks to Tim Nash for pointing out the concerns around caching and performance with this feature.

Watch the video

About the author

Mark is the lead WordPress developer at Highrise Digital. He has been working with WordPress for over 15 years, way back to 2005. He focuses on back-end development, integrating the website build with WordPress so everything can be editable.