Sphinx Not Found Page

Warnings

• gotcha When testing locally by opening `404.html` directly (e.g., via `file://` in a browser), assets like CSS and JavaScript may appear broken. This is expected behavior because the extension generates absolute URLs, which require a web server to resolve correctly.
  Fix: Deploy your documentation to a web server (e.g., Read the Docs, GitHub Pages) or serve it locally using a proper HTTP server (not just `file://`).
• gotcha Simple local web servers (like Python's `http.server`) often do not have a default handler for 404 error codes. This means they may not serve the generated `404.html` when a page is truly not found. For production deployments, your web server (e.g., Nginx, Apache) must be configured to handle 404 errors by serving the generated `404.html` with a 404 HTTP status code.
  Fix: Configure your web server's error handling. For Nginx, use `error_page 404 /404.html;`. For Apache, use `ErrorDocument 404 /404.html`. Ensure the server returns an actual 404 HTTP status code, not a 'soft 404' (200 OK with a 'not found' message).
• gotcha The `notfound_urls_prefix` configuration option (used for hosting on GitHub Pages, sub-projects on Read the Docs, etc.) *must* start and end with a `/` if it's a string, unless it is set to `None`. Failure to do so can lead to incorrect asset paths and broken 404 pages.
  Fix: Always ensure `notfound_urls_prefix` is correctly formatted, for example: `notfound_urls_prefix = '/my_repo/'` for GitHub Pages, or `notfound_urls_prefix = None` for single-version Read the Docs projects.
• breaking Sphinx 7.2.x introduced API changes (e.g., use of `pathlib.Path` objects instead of strings for paths, changes to the `toctree` adapter) which caused compatibility issues with `sphinx-notfound-page` (and other Sphinx extensions/themes) that relied on the previous API.
  Fix: Ensure you are using a version of `sphinx-notfound-page` that is compatible with your Sphinx version. For earlier issues, users often had to temporarily pin Sphinx to `<7.2` until the extension was updated. Version 1.1.0 should be compatible with recent Sphinx releases.
• gotcha If you create a custom `404.rst` file to define your 404 page content, Sphinx may issue a warning that the document is not included in any `toctree`.
  Fix: Add `:orphan:` metadata as the very first line in your `404.rst` file to suppress this warning. Example: `:orphan: My 404 Page`.

Install

• pip install sphinx-notfound-page Install from PyPI

Imports

• notfound.extension

  extensions = ['notfound.extension']

  Add 'notfound.extension' to the list of Sphinx extensions in your conf.py file.

Quickstart

To quickly enable `sphinx-notfound-page`, install it via pip and then add `'notfound.extension'` to the `extensions` list in your Sphinx `conf.py` file. For custom content, you can define `notfound_context` directly in `conf.py` or create a `404.rst` file and set `notfound_template = '404.rst'`. Remember to add `:orphan:` to the top of any custom `404.rst` file to prevent Sphinx warnings.

# conf.py

# Existing extensions list
extensions = [
    # ... other extensions
    'notfound.extension',
]

# Optional: Customize 404 page content directly in conf.py
notfound_context = {
    'title': 'Page Not Found',
    'body': '<h1>Oops! This page does not exist.</h1>\n\n<p>Please check the URL or navigate from the <a href="/">homepage</a>.</p>',
}

# Optional: Use a custom 404.rst file for content
# notfound_template = '404.rst'

# If using a custom 404.rst, ensure it has the :orphan: metadata
# Example 404.rst content (place next to conf.py):
# :orphan:
#
# Error 404: Page Not Found
# =========================
#
# The page you are looking for does not exist. Please check the URL.