Repository navigation
Add a themed 404 page and a page-level sitemap - #217
Merged
Merged
Conversation
Read the Docs serves a generic 404 for a custom domain, losing the site's theme and navigation; sphinx-notfound-page generates one it serves instead. Its links have to be absolute, since a 404 is served from any depth. Read the Docs' own sitemap.xml lists version roots, so sphinx-sitemap complements it with the individual pages.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Adds sphinx-notfound-page and sphinx-sitemap.
Why each one
404 page. On a custom domain, Read the Docs serves a generic 404 that has none of our theme or navigation.
sphinx-notfound-pagegenerates a404.htmlthat Read the Docs serves instead. The subtlety is that a 404 is served from any URL depth, so relative asset links would break — the extension rewrites them absolute:Verified: 28 KB, Furo-themed (
sidebar-drawermarkup present), and zero remaining../links.Sitemap. Read the Docs generates a
sitemap.xmllisting version roots, not individual pages.sphinx-sitemapcomplements it with a page-level sitemap — 93 URLs.The two settings that aren't obvious
html_baseurlwas not previously set. It does double duty: Sphinx emits it as<link rel="canonical">, and sphinx-sitemap builds every URL from it.sitemap_url_scheme = '{link}'is required because of that value.html_baseurlalready carries the language and version, and the default scheme ({lang}{version}{link}) would repeat both — and would useversionfromconf.py(9.0) rather than thelatestthe site is actually served at, producing URLs that 404.sitemap_excludesdrops404.html,search.htmlandgenindex.html. The 404 in particular should never be advertised to a crawler; it was in the first build I ran.glossary.htmlis real content and stays.Verification
sphinx -b html -W --keep-going— succeeds, zero warningsen/latestprefixdoc8,pre-commit run --all-files,npm run lint— all clean