404 page is not rendered properly when mkdocs-material is used

[renardeinside]

Details

• Read the Docs project URL: https://readthedocs.org/projects/dbx/

Expected Result

When running mkdocs serve locally, 404 page is rendered as follows:

Actual Result

However when deployed to readthedocs something breaks (maybe during render?), for example

https://dbx.readthedocs.io/notfound

Leads to this:

Code of mkdocs.yml is provided here, readthedocs.yaml is here

Any help would be much appreciated.

[renardeinside]

not sure if this might be helpful, here is the console log from browser:

[stsewd]

@renardeinside this is since the 404 page from mkdocs is linking to the styles as absolute links to / (/assets/stylesheets/main.69437709.min.css), but your docs are being serve from /en/latest/ (/en/latest/assets/stylesheets/main.69437709.min.css), not from /.

For sphinx we have an extension that changes the links to be absolute to the default version https://github.com/readthedocs/sphinx-notfound-page. For MkDocs I'm not sure about the solution, maybe setting https://www.mkdocs.org/user-guide/configuration/#site_url could work.

[renardeinside]

hi @stsewd ,
thanks a lot for quick reply.

I've site_url set in my mkdocs as per link here:

site_name: dbx
site_description: 🧱Databricks CLI eXtensions - aka dbx is a CLI tool for development and advanced Databricks workflows management.
site_url: https://dbx.readthedocs.io/

is it something missing or I'm doing wrong?

[renardeinside]

btw, this issue is also reproducible even with the example linked in the readthedocs doc as an example.

[stsewd]

@renardeinside your site URL needs to have /en/latest/.

btw, this issue is also reproducible even with the example linked in the readthedocs doc as an example.

yeah, but this problem isn't related to RTD itself, you will have the same problem in any other hosting where the docs are served in a path different from /.

And if setting the site URL works, it should probably be set differently for each version (/en/latest/, /en/stable/, etc)

[stsewd]

And if setting the site URL works, it should probably be set differently for each version (/en/latest/, /en/stable/, etc)

This is related to #4820 and #8529.

[renardeinside]

huge thanks @stsewd , adding /en/latest/ indeed fixed the issue 👍