2.4.4.2. Custom 404 Page¶
Both GitHub Pages and ReadTheDocs allow you to customize your website’s 404 error page, i.e., the page that is displayed when a user tries to access a page that does not exist. This is already implemented in the documentation website provided to you by the PyPackIT template repository.
2.4.4.2.1. Customization¶
To change the customized 404 error page of your website,
simply edit the 404.md
file in the source
subdirectory of your website directory
(default: ./docs/website/source/404.md
).
2.4.4.2.2. Implementation Details¶
ReadTheDocs
looks for an HTML file either at /404.html
or /404/index.html
,
relative to the root of your documentation website, while
GitHub Pages
only looks for /404.html
.
Since your documentation website is by default built using Sphinx’s dirhtml
builder,
the 404.md
file is automatically converted to 404/index.html
by Sphinx,
and is therefore not recognized by GitHub Pages.
To solve this issue, a 404.html
file is also provided next to the 404.md
file,
which only contains a redirect to the 404/index.html
file.
Since Sphinx doesn’t automatically include non-source files (i.e., files that are not .md
or .rst
files)
in the built website, the 404.html
file is added to the html_extra_path
list in the conf.py
file,
which tells Sphinx to include it in the built website as is.
This way, both ReadTheDocs and GitHub Pages will be able to find the 404.html
file,
which will then redirect them to the actual customized 404 error page at 404/index.html
.