Add a 404 Error Page

If the web server cannot locate the page for a URL, it returns a 404 status code to the browser (instead of the normal 200 status code). This can happen if a visitor clicks on a broken link from within the site or a search engine or by mistyping the URL in the browser location bar.

Rather than showing the visitor a blank page or a low-level error message, the web server will typically display the contents of the 404 error page (herein, the 404 page).

To serve the 404 page, the web server looks for the file 404.html located at the root of the published site. The contents of this file is used in place of the HTML the visitor would have seen. The visitor is not redirected to another page, so the original URL is still visible in the browser location bar.

Let’s learn how to define the 404 page and add it to your Antora site.

In an Antora site, the 404 page is created using a layout template provided by the UI. For this to work, the UI must define a layout template named 404 located at the path layouts/404.hbs. Antora uses this template to generate the 404.html file, which it then outputs to the root of your published site.

If you use or extend the default UI, the layout template for the 404 page is already provided for you.

The 404 layout template is compiled with a reduced UI model that does not include any information about the current page (since there isn’t one) except for page.title and page.layout. The template has access to all other variables in the UI model, such as uiRootPath and site.components.

Unlike for regular pages, the uiRootPath and siteRootPath template variables are root-relative paths in the 404 template. This is necessary for the 404 page to work correctly when served by the server. That’s because the 404 page content is served from whatever URL the visitor originally requested.

Antora only generates the 404 page if the site.url key in the playbook has a value. The assumption is that if the site URL is specified, the site is going to be published to a web server.

The value of the site.url key can either be an absolute URL or a root-relative path, as explained on the site URL page. The path segment can be non-empty, which will be addressed in the next section.

Normally, there’s nothing else you need to do make the 404 page work. The web server automatically picks up the 404.html file at the root of the published site and uses it when the visitor lands on a missing page.

However, if you’re publishing your site to a subpath of a domain (e.g., https://example.org/site-a), additional configuration is required.

When the URL of your site includes a path segment, the 404 page for your site will no longer be located at the web server root. Instead, it will be located under a subpath with the rest of the files. The problem is, the web server doesn’t know this subpath is significant (meaning it doesn’t know the subpath is the boundary of a discrete site). As a result, the web server will not know to serve this 404 page in place of a missing page. So we have to tell it to do so. We must configure the web server to use the 404 page under the subpath (e.g., /site-a/404.html) instead of the one at the default location (i.e., /404.html) when serving files for the site.

Here are the three steps required to get this set up. We’ll assume the domain is example.com, the subpath is site-a, and the web server is nginx.

The Antora demo is an example of this configuration (except the GitLab Pages server automatically maps the 404 page from the subpath for you). See https://antora.gitlab.io/demo/docs-site/component-b/2.0/no-such-page.html. Notice that the URL for the CSS file is the root-relative path /demo/docs-site//css/site.css_.