ddev: readthedocs: Broken layout on 404 page

Describe the bug When accessing a stale or otherwise invalid documentation link, the layout of the returned page is broken. The reason seems to be invalid asset paths which are missing the base path. Example:

valid page: https://ddev.readthedocs.io/en/stable/assets/stylesheets/main.b8ac9624.min.css
404 page: https://ddev.readthedocs.io/assets/stylesheets/main.b8ac9624.min.css

To Reproduce Visit the URL https://ddev.readthedocs.io/en/latest/users/providers/user-defined/ (referenced in https://github.com/drud/ddev/releases/tag/v1.17.0-alpha5).

Screenshots

Additional context Ideally, stale paths should be redirected to the current paths (see e.g. https://docs.readthedocs.io/en/stable/user-defined-redirects.html).

About this issue

Original URL
State: closed
Created 3 years ago
Reactions: 1
Comments: 19 (19 by maintainers)

Most upvoted comments

@rfay I follow the related issues, and afair there wasn’t any movement. But since I’ve already set up a readthedocs version of the docs for #3232 I might take a stab at this myself in the coming days.

mootari on Sep 9, 2021

Sorry for the delay, finally found the time to look into it. Here’s what I think the core problem is:

mkdocs-material generates relative asset paths for all pages, except for the 404 page. This page is only generated once and served at arbitrary URIs, thus using absolute asset paths. For this to work, site_uri must be configured correctly.

Possible solutions:

Redirect: Via the readthedocs dashboard, create a prefix redirect from /assets/ to /en/stable/assets/. This will only work properly (if at all) for the docs at /en/stable/. If there are other versions, these might fail with this solution.
Environment variables: Read The Docs provides a few environment variables which can be referenced during a build. mkdocs supports env vars within a config yaml, but offers not means to concatenate multiple variables.
readthedocs does not yet expose the base URL as a single env var. This feature is tracked in https://github.com/readthedocs/readthedocs.org/issues/8260. Once this change is in, setting site_uri should become trivial.

mootari on Jul 4, 2021