Skip to content
Branch: master
Find file Copy path
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
64 lines (51 sloc) 2.45 KB
title linktitle description date publishdate lastmod categories keywords menu weight draft aliases toc
Custom 404 Page
404 Page
If you know how to create a single page template, you have unlimited options for creating a custom 404.
page not found
parent weight

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 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/


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

{{< code file="layouts/404.html" download="404.html" >}} {{ define "main"}}

<a href="{{ "/" | relURL }}">Go Home

{{ end }} {{< /code >}}

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. 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.
  • Amazon AWS S3. When setting a bucket up for static web serving, you can specify the error file from within the S3 GUI.
  • Amazon CloudFont. You can specify the page in the Error Pages section in the CloudFont Console. Details here
  • Caddy Server. Using errors { 404 /404.html }. Details here
  • Netlify. Add /* /404.html 404 to content/_redirects. Details Here

{{% note %}} hugo server will not automatically load your custom 404.html file, but you can test the appearance of your custom "not found" page by navigating your browser to /404.html. {{% /note %}}

You can’t perform that action at this time.