404 error page configuration

404 error pages are an important element of any site; even if a site is well-managed there's always the chance that someone will mistype a link, or change a page URL without cleaning up the associated links. With an error page, you can not only let users know that something has gone wrong, but also redirect them to alternative resources to encourage them to keep browsing your site.

Though earlier Publii betas did not include 404 pages, the July update introduced built-in support for 404 pages in all of the themes included with the standard Publii package.

Configuring 404 pages in Publii themes

In the theme configuration file (config.json) there is a renderer section; here we can see whether a theme has 404 pages enabled and what the files will be named.

Note: Once the 404 page is enabled a new file called 404.hbs will be created, which contains the content for the 404 page.

In the renderer section is one and in the URLs (Settings)  the second option that you can configure for your error pages:

...
"renderer": {
    ...
    "create404page": false
    ...
},
...

The create404page option is used to enable or disable error pages; by default this is set to false in new Publii sites. URLs section (Settings) offers option to define the name of the file containing the 404 error page which will be rendered when generating the website.

Host-dependent 404 page configuration

The configuration of the 404 page depends on where the page is stored, and the type of hosting that is being used. Let's look at the configuration for each type in turn:

Apache servers (synchronizing via FTP, FTPS, SFTP)

For most standard servers the following line should be added to the .htaccess file:

ErrorDocument 404 /404.html

The 404.html part of this line may differ depending on the name of the page set in the renderer section of the configuration file mentioned earlier.

If your website files are located somewhere other than the main folder of your FTP then you will need to modify the path to the 404.html file to point to the website folder, such as:

ErrorDocument 404 /name/folder/404.html

To edit the .htaccess file we can use the .htaccess editor built into Publii; after opening Publii, click on the Tools section in the left menu then click on the .htaccess Editor option to open the editor.

Note: If you already have an .htaccess file on your server before syncing Publii to it, then the existing file will be replaced by the new one generated by Publii.

Github Pages, Netlify, Google Cloud

These hosts generally do not need any additional configuration; simply having a 404.html file is enough. The 404 page will be displayed in the event that there are no other files.

The only thing that should be taken care of is to ensure that the name of the 404 file in the theme configuration is left as the default 404.html.

Amazon S3

When activating the page hosting service in the Amazon S3 configuration you will need to define a redirect rule for when a 404 error occurs: