Adding 404 page for the website

[speco29]

@OriolAbril

This pull request creates a 404.html page for the website, creates a deploy.yml file

[OriolAbril]

This is basically duplicating https://github.com/numfocus/DISCOVER-Cookbook/blob/main/.github/workflows/build-gh-pages.yml. I don't think we want this workflow at all

[speco29]

I will delete this file deploy.yml also I am thinking to close this pull request and start a new pull request that has everything in a correct way, I opened this as a draft PR because I knew it would conatin some mistakes and changes would be required.

[OriolAbril]

If it is easier do not hesitate to open a different PR, but if it is only to keep the "commit history clean" I personally don't care at all, and it should be possible to merge with "squash and merge" so the whole PR becomes a single commit and no track of the PR commits remain if that were to worry you.

[OriolAbril]

Have you deployed this to your preview? I would like to test how it handles a variety of broken urls, getting the 404 page to use the website theme consistently is a bit tricky so we might need to use https://sphinx-notfound-page.readthedocs.io/en/latest/

That being said, I am not sure having the 404 page use the theme will be the best user experience (for example, I don't think the switchers will work from the 404 page)

[speco29]

Have you deployed this to your preview? I would like to test how it handles a variety of broken urls, getting the 404 page to use the website theme consistently is a bit tricky so we might need to use https://sphinx-notfound-page.readthedocs.io/en/latest/

That being said, I am not sure having the 404 page use the theme will be the best user experience (for example, I don't think the switchers will work from the 404 page)

Yes, I deployed it. It goes with the theme and looks something like this:

It does look a bit weird though, when I tried to change the look of 404 page, it got even more weirder.
Is it necessary that this 404 page must build from 404.md file ? Can't we just build it directly and then give it style of our own?

[OriolAbril]

We can have a raw html page "outside the theme" yes, no need for it to be markdown first. The 404 page will also be global to versions and a future version might change the theme too

[OriolAbril]

I am not sure we want this behaviour. Maybe we could check the url the 404 is being generated for? Is that possible?

The main issue I expect out of this. My computer and browser are in catalan. Big projects like linux distros or firefox have a catalan translation, but most places do not (the cookbook will probably be here). Now I don't care so much, but if both languages are available I often prefer spanish. If I understand the code correctly with this setup I would switch from browsing the Spanish translation to the english 404

I was originally thinking about having all the languages there all at once. But it won't be nice once languages start to grow.

[speco29]

I think Instead of relying on navigator.language, we can extract the intended language from the URL path — like /es/, /fr/, etc. That way, the 404 page stays in sync with the rest of the site's language context.

Something like this:

// Determine language from URL path — fallback to 'en'
const urlLang = location.pathname.split("/")[1] || "en";
const lang = translations[urlLang] ? urlLang : "en";

// Update content with appropriate language
document.getElementById("title").textContent = translations[lang].title;
document.getElementById("message").textContent = translations[lang].message;
document.getElementById("suggestion").textContent = translations[lang].suggestion;
document.getElementById("what-do").textContent = translations[lang].whatDo;
document.getElementById("home").textContent = translations[lang].home;
document.getElementById("report").textContent = translations[lang].report;
document.getElementById("footer").textContent = translations[lang].footer;

Also since the 404 stands apart from our standard navigation, we could offer a subtle dropdown to switch languages.
A subtle dropdown language selector comes in — right inside our 404 page. Like a mini, standalone version of our main language switcher.

<select id="language-switcher">
  <option value="en">English</option>
  <option value="es">Español</option>
  <option value="fr">Français</option>
</select>

then on addition:

document.getElementById("language-switcher").addEventListener("change", function () {
  const lang = this.value;
  window.location.href = `/${lang}/404.html`;
});

This allows users to switch to the correct translated 404 page even if they’ve landed on the wrong one — much better for experience and accessibility.
What do you think @OriolAbril ?

[OriolAbril]

This sounds better, especially the option to allow users to choose. It is basically impossible to accurately guess/predict which language will someone request when reading a page. Url based default+allow choosing will be a good user experience I think

[aterrel]

closing for #344