Add a 404 Error Page

Don’t worry, you haven’t landed on a missing page. This page is about the 404 error page and how to add it to your published site.

What is 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.

Define the 404 page

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.

Activate the 404 page

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.

If Antora does not find a layout template in the UI bundle (or supplemental UI) with the name 404, it will not generate a 404 page for your site (even if the site.url key is set in the playbook).

Configure the 404 page when publishing to a subpath

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.

  1. Define site.url with the subpath in the playbook file, either using an absolute URL:

    site:
  url: https://example.com/site-a

    or a root-relative path:

    site:
  url: /site-a
    The site URL defined in the playbook must include the subpath. Otherwise, the URLs in the 404 page will not be correct (e.g., the URL for the CSS file).

  2. Configure nginx to use the 404.html from the subpath folder for any missing URL that falls under that subpath:

    location /site-a/ {
  error_page 404 /site-a/404.html;
}
    Adjust the subpath location to match the subpath for your site.

  3. Copy the site files generated by Antora to the subpath under the web server root:

    $ rsync -r --delete build/site/ /usr/share/nginx/html/site-a

    In other words, the subpath folder must be located in the web server root or the root of the virtual host.

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 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_.