404.md (3266B)
1 ---
2 title: Custom 404 Page
3 linktitle: 404 Page
4 description: If you know how to create a single page template, you have unlimited options for creating a custom 404.
5 date: 2017-02-01
6 publishdate: 2017-02-01
7 lastmod: 2017-03-31
8 categories: [templates]
9 keywords: [404, page not found]
10 menu:
11 docs:
12 parent: "templates"
13 weight: 120
14 weight: 120 #rem
15 draft: false
16 aliases: []
17 toc: false
18 ---
19
20 When using Hugo with [GitHub Pages](https://pages.github.com/), you can provide your own template for a [custom 404 error page](https://help.github.com/articles/custom-404-pages/) 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.
21
22 404 pages will have all the regular [page variables][pagevars] available to use in the templates.
23
24 In addition to the standard page variables, the 404 page has access to all site content accessible from `.Pages`.
25
26 ```
27 ▾ layouts/
28 404.html
29 ```
30
31 ## 404.html
32
33 This is a basic example of a 404.html template:
34
35 {{< code file="layouts/404.html" download="404.html" >}}
36 {{ define "main"}}
37 <main id="main">
38 <div>
39 <h1 id="title"><a href="{{ "/" | relURL }}">Go Home</a></h1>
40 </div>
41 </main>
42 {{ end }}
43 {{< /code >}}
44
45 ## Automatic Loading
46
47 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:
48
49 * [GitHub Pages](/hosting-and-deployment/hosting-on-github/) and [GitLab Pages](/hosting-and-deployment/hosting-on-gitlab/). The 404 page is automatic.
50 * Apache. You can specify `ErrorDocument 404 /404.html` in an `.htaccess` file in the root of your site.
51 * Nginx. You might specify `error_page 404 /404.html;` in your `nginx.conf` file. [Details here](https://nginx.org/en/docs/http/ngx_http_core_module.html#error_page).
52 * Amazon AWS S3. When setting a bucket up for static web serving, you can specify the error file from within the S3 GUI.
53 * Amazon CloudFront. You can specify the page in the Error Pages section in the CloudFront Console. [Details here](https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/custom-error-pages.html)
54 * Caddy Server. Use the `handle_errors` directive to specify error pages for one or more status codes. [Details here](https://caddyserver.com/docs/caddyfile/directives/handle_errors)
55 * Netlify. Add `/* /404.html 404` to `content/_redirects`. [Details Here](https://www.netlify.com/docs/redirects/#custom-404)
56 * Azure Static website. You can specify the `Error document path` in the Static website configuration page of the Azure portal. [More details are available in the Static website documentation](https://docs.microsoft.com/en-us/azure/storage/blobs/storage-blob-static-website).
57 * DigitalOcean App Platform. You can specify `error_document` in your app specification file or use control panel to set up error document. [Details here](https://docs.digitalocean.com/products/app-platform/references/app-specification-reference/).
58
59 {{% note %}}
60 `hugo server` will not automatically load your custom `404.html` file, but you
61 can test the appearance of your custom "not found" page by navigating your
62 browser to `/404.html`.
63 {{% /note %}}
64
65 [pagevars]: /variables/page/