404 page with mike and versioning

[niden]

Hello all

I am trying to set up a 404 page.

The site is hosted in GitHub pages and whenever there is an error in the URL, the regular 404 page of GitHub appears.

I added a 404.html page

{% extends "main.html" %}

{% block htmltitle %}
<title>404</title>
{% endblock %}

{% block content %}
Ooops! Something went wrong.
 endblock %}

in the overrides folder (./overrides/404.html) but it does not appear on the site.

I did check the gh-pages branch and the 404.html is generated correctly.

Any pointers are appreciated.

[niclasheinz]

Hi @niden

Have you set the overrides-Folder in the mkdocs.yml file like this:

theme:
  name: material
  custom_dir: overrides
  

References:

• https://squidfunk.github.io/mkdocs-material/customization/?h=custom#setup-and-theme-structure

[niden]

Yes and the overrides folder looks like this

overrides
    404.html
    main.html

[niclasheinz]

Yeah got it.

Try this please:

{% extends "main.html" %}

{% block htmltitle %}
<title>404</title>
{% endblock %}

{% block content %}
Ooops! Something went wrong.
{% endblock %}

You forgot this thing {% at the last endblock.

[kamilkrzyskow]

EDIT: This might turn in further discussion, so I'll move the message below. Sorry about the double notification 🫡

[niden]

@niclasheinz That was a typo during copy/paste :)

[kamilkrzyskow]

There is no 404.html in the root of the gh-pages branch:

• https://github.com/phalcon/documentation/tree/gh-pages

When an invalid URL loads then the back-end server, GitHub Pages loads the base_url/404.html file, and since your repository doesn't include that then it loads the GitHub 404 page.

MkDocs generates only static HTML pages, there is no "browser application" which would resolve the path to the proper 404 page of a given version.

The root index.html file replaces the location with /latest, I don't know what generates this source 🤔 Does mike add it?
The index.html source of https://mkdocs-material.github.io/example-versioning/ is a bit different yet the same.
There is no 404.html file at the root, so I guess the responsibility to add it is on mike?
There is a related issue upstream:

• Provide a 404 page jimporter/mike#72

Also the 404 page being a static file would still have to have some JavaScript to preserve navigation links for the currently selected version.

References to similar threads to get a better picture:

• [Bug?] 404 page not generated for selected language ultrabug/mkdocs-static-i18n#284 (comment)
• 404 rendering fails #7595

[kamilkrzyskow]

Great that it was a quick fix 💪 However, I will point out that you haven't followed the reproduction guidelines and you haven't mentioned mike or the multi versioning setup.

Hence Niclas assumed it's the default configuration, while I took the time to spy on your profile and found the fortunately for us public repository, which resulted in a fix ✌️

[niden]

For those that might need it, I wrote a small JS snippet to read the versions.json file that mike generates and based on the version in the URL it redirects you to the appropriate 404 page.

Assuming that your site is https://example.com/version/page, if you enter something that does not exist https://example.com/version/unknown you will end up in https://example.com/version/404. If no version is found, it will use latest as the version.

This is the contents of the /404.html file

    <title>404</title>

    <script>
        document.addEventListener('DOMContentLoaded', function() {
            fetch('versions.json')
                .then(response => response.json())
                .then(versions => {
                    const url = window.location.pathname;
                    const versionMatch = url.match(/^\/([^\/]+)\//);
                    let version = 'latest';

                    if (versionMatch) {
                        const detectedVersion = versionMatch[1];
                        const versionExists = versions.some(v => v.version === detectedVersion);
                        if (versionExists) {
                            version = detectedVersion;
                        }
                    }

                    window.location.href = `/${version}/404`;
                })
                .catch(error => {
                    console.error('Error fetching versions:', error);
                    window.location.href = '/latest/404';
                });
        });
    </script>

[niden]

@kamilkrzyskow the investigator :) Sorry, about that and thanks again.

[kamilkrzyskow]

While being on https://docs.phalcon.io/5.7/introduction/ adding an invalid path to the URL results in https://docs.phalcon.io/5.8/404.html
with no ability to go back with the back button. So the UX is not so great, I've commented on such things also in the other thread. The browser console shows that an invalid versions.json path is fetched

[niden]

I fixed the versions.json not found but now the search/search_index.json doesn't load (again not found). I need to dig into that more. The back button though works.