Custom 404 page

When using Hugo with GitHub Pages, you can provide your own template for a custom 404 error page by creating a 404.html template file in the root of your layouts folder. When Hugo generates your site, the 404.html file will be placed in the root.

404 pages will have all the regular page variables available to use in the templates.

In addition to the standard page variables, the 404 page has access to all site content accessible from .Pages.

▾ layouts/
    404.html

404.html

This is a basic example of a 404.html template:

{{ define "main" }}
  <main id="main">
    <div>
      <h1 id="title"><a href="{{ "" | relURL }}">Go Home</a></h1>
    </div>
  </main>
{{ end }}

Automatic loading

Your 404.html file can be set to load automatically when a visitor enters a mistaken URL path, dependent upon the web serving environment you are using. For example:

• GitHub Pages, GitLab Pages and Cloudflare Pages. The 404 page is automatic.
• Apache. You can specify ErrorDocument 404 /404.html in an .htaccess file in the root of your site.
• Nginx. You might specify error_page 404 /404.html; in your nginx.conf file. Details here.
• Amazon AWS S3. When setting a bucket up for static web serving, you can specify the error file from within the S3 GUI.
• Amazon CloudFront. You can specify the page in the Error Pages section in the CloudFront Console. Details here
• Caddy Server. Use the handle_errors directive to specify error pages for one or more status codes. Details here
• Netlify. Add /* /404.html 404 to content/_redirects. Details Here
• Azure Static Web App. set responseOverrides.404.rewrite and responseOverrides.404.statusCode in configfile staticwebapp.config.json. Details here
• Azure Storage as Static Web Site Hosting. You can specify the Error document path in the Static website configuration page of the Azure portal. Details here.
• DigitalOcean App Platform. You can specify error_document in your app specification file or use control panel to set up error document. Details here.
• Firebase Hosting: /404.html automatically gets used as the 404 page.