How do I get readthedocs to use a custom 404 page?

[sg-s]

Details

• Read the Docs project URL: https://xolotl.readthedocs.io/en/master/

Expected Result

If I go to https://xolotl.readthedocs.io/en/master/fsdf, I expect to see the 404 page that is part of my theme (which is what I see when I build locally)

Actual Result

Instead, I get the default readthedocs 404 page with the maze.

I don't understand why the 404.html that is built as part of my theme isn't being used.

I can't find any setting in readthedocs that specifies custom 404 pages

I've looked at these links, and I don't think they help:

• Improve 404 pages #2551
• https://docs.readthedocs.io/en/latest/user-defined-redirects.html
• Best Practices Question: redirects for non-existent docs #4948

Any help appreciated!

[humitos]

Hi @sg-s and thanks for your report.

Currently, this is not possible.

There are more discussion around this and the problems of different implementations at #353 (actually, it feels this issue is a duplicated of that one)

[sg-s]

@humitos thanks -- for clarification, i am using the material theme, and i note that in the docs for that theme, they have a functional 404 page:

https://squidfunk.github.io/mkdocs-material/dsf

is this because they're not using readthedocs, and instead hosting on github?

[humitos]

is this because they're not using readthedocs, and instead hosting on github?

I suppose, yes.

I hope RTD support this soon. It's something that I've wanting for some time.

I'm closing this issue here. Please, subscribe to the one that I linked here since all the discussion will happen there mostly.

Thanks!

[humitos]

@sg-s hey! we do support custom 404 pages now!

Your project now shows your custom page at: https://xolotl.readthedocs.io/en/master/notfound

The only thing missing is fixing the resources (css, js, images, etc) to use absolute URLs so they are found by the browser properly.

[sg-s]

@humitos Thanks! Could you elaborate a little? Which resources do I fix? Do I need a redirect?

[stsewd]

@sg-s all links to css/js are relative, those should be absolute. Since the 404 page can be displayed in any subpage /foo/bar/404.thml not just in /404.hml

[sg-s]

Great, thanks. Sounds like I need to modify the theme I'm using and replace all relative links with absolute links

[humitos]

@sg-s let us know if after changing the links it does work! ;)