Improve 404 pages

[wolph]

Details

When stumbling upon a 404 it's currently impossible (except by modifying the URL yourself) to get back to the documentation. The 404 page shows a link to the RTD homepage, to the Github and several other links. But not a single link to the root and/or other versions of the documentation.

To illustrate, Google sent me to this out of date documentation set: http://docs.wagtail.io/en/v0.7/core_components/images/index.html After that I clicked on the link to go to the more recent version of the docs: "You are not using the most up to date version of the library. 1.8 is the newest version." Which ends up over here: http://docs.wagtail.io/en/v1.8/core_components/images/index.html

Naturally RTD can't fix the broken links, but having a link to http://docs.wagtail.io/en/v1.8/ and/or to http://docs.wagtail.io/ would be a lot easier than having to manipulate the url yourself.

Expected Result

A 404 page with a bunch of useful project related links to click

Actual Result

A 404 page with the maze and no project related links.

[wolph]

After browsing the RTD source a little I noticed the support for suggestions: https://github.com/rtfd/readthedocs.org/blob/499a74076f0debae09acc1d4c4eeeab03f8f557e/readthedocs/templates/404.html#L14-L31

Has that feature been fully implemented yet? A further search of the source reveals nothing else for suggestions: https://github.com/rtfd/readthedocs.org/search?utf8=%E2%9C%93&q=suggestion

[wolph]

It appears to originate from this pull request: https://github.com/rtfd/readthedocs.org/pull/678 But I can't find much else about it... it appears that code has disappeared since

[stsewd]

This was removed in https://github.com/rtfd/readthedocs.org/pull/2191

Here https://github.com/rtfd/readthedocs.org/pull/2191/commits/64faed20fd3a5672f9b34c4b4565a567eba3deec

[humitos]

If this is finally implemented (https://github.com/rtfd/readthedocs.org/pull/5130#issuecomment-460248089), we won't need to do anything extra here I suppose.

[wolph]

That depends on what the new default 404 page will be I suppose. Just because you can customize it doesn't mean that everyone will.

[humitos]

Even without customizing it, the pages will have the flyout menu (with all the versions) and the logo in the top left that readers can click to "stay in the project's docs site" instead of being blocked as they were before.

[stale[bot]]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.

[humitos]

I'm marking this issue as Accepted since the extension that I added to our docs that generates nice 404 pages like https://docs.readthedocs.io/en/latest/notfound it's not the default behavior and needs customization from the author.

So, this issue is still valid and we will eventually need to do more work here to have a better default 404 page.

[wolph]

Indeed. Ideally it should show search results that match your page

[wolph]

After ending up at a dead-end again over here: https://websockets.readthedocs.io/en/stable/api.html

I'm wondering... can't we at least add a simple link to the main page/domain? Something like this: <a href="/">Back to the main page</a>

That would already improve the experience a lot and won't (as far as I can see) really break anything.

[stsewd]

+1 on adding a link back to the main site and a search box.

[ericholscher]

This focused on documentation pages that we host, and making them more useful for users. Our sphinx-notfound-page extension helps with this, but we should make the default one a bit nicer. This change should only apply to our proxito settings, so it applies to docs pages & not the dashboard.

[benjaoming]

There are some good tools available for documentation project owners to use, I wonder if that could be added to a contextualized 404.

Kind of like...

This is a 404

[primary text for users]

Are you a documentation developer?

* Using RTD, you can add custom redirects when you move pages: Read more...
* Customize your 404 page by using the Sphinx extension: Read more...

[benjaoming]

There's a more detailed suggestion for contextualized messages in https://github.com/readthedocs/readthedocs.org/pull/9657/ - I will add them to the PR for further discussion of the copy.