Please check the URL or navigate from the homepage.
',\n}\n\n# Optional: Use a custom 404.rst file for content\n# notfound_template = '404.rst'\n\n# If using a custom 404.rst, ensure it has the :orphan: metadata\n# Example 404.rst content (place next to conf.py):\n# :orphan:\n#\n# Error 404: Page Not Found\n# =========================\n#\n# The page you are looking for does not exist. Please check the URL.","lang":"python","description":"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."},"warnings":[{"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://`).","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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).","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"breaking","affected_versions":"Sphinx 7.2.0 (and potentially early 7.2.x releases)"},{"fix":"Add `:orphan:` metadata as the very first line in your `404.rst` file to suppress this warning. Example: `:orphan:\n\nMy 404 Page`.","message":"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`.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-12T00:00:00.000Z","next_check":"2026-07-11T00:00:00.000Z"}