Add links to jump to latest version of docs

[pdavies]

Hello! 👋

This PR addresses #1917 . It adds support for specifying which version is the latest via docs_config.js:

var versionNodes = [
    { version: 'v1.0.0', url: '/foo'},
    { version: 'v2.0.0', url: "/bar", latest: true },
    { version: 'v0.34.0-dev', url: "/baz" }
];

which will trigger a warning hyperlink to the latest version when viewing other versions:

It is not required to have a latest version in docs_config.js. Existing docs_config.js files will continue to produce the existing behaviour with no warning links.

Rather than try to determine which version is the latest through javascript logic, it seemed more appropriate to delegate to the author of docs_config.js, for example hexdocs. This avoids the risk of behaviour that differs from the documentation host's opinion on which version is the latest. This does mean that the PR doesn't do anything interesting without a small enhancement to (in practice) hexdocs.

This PR has the drawback that docs published prior to this PR will not get warnings. But due to the way exdocs works, I don't see how any attempt at fixing #1917 could get around this.

[josevalim]

This looks good to me but the indicator is calling too much attention. What if we keep only the warning sign? And then on mouse over it says this is not the latest version and you can click it to update?

[halostatue]

@josevalim I think that it would be better to have the words than the warning sign for mobile users, since there is no "mouse over" capability there. I think the colours could definitely be muted, but from an accessibility point of view, words are better.

[josevalim]

On mobile, we usually render the project name and version on every page, below the title, because the sidebar is not open. Shall we have the go to latest there instead (for mobile)?

[halostatue]

I think so, but it might be something worth rethinking the render, because having that as a parenthetical next to a parenthetical is odd.

[pdavies]

Thanks for the feedback!

Visuals: I agree the white on red is unpleasant and should be toned down. It also did not play nicely with light/dark theming. However there is a balance to strike - if it isn't eyecatching, it isn't useful. I've revised the appearance to be theme-aware and less painful on the eyes. It still isn't beautiful but I'd need to defer to someone with better frontend design skills to improve it any further!

Mobile view: I hadn't given any thought to this. My preference would be to tackle that separately - more honestly for someone else to tackle that separately. This is mainly because I'm not sure how I would get the necessary information to module_template.eex in a nice way.

[halostatue]

The Rust docs say "go to latest version", not "go to latest"; I realize we have limited space because this is in the sidebar, but I wonder if it might instead be possible to say something like View latest (v{{latestVersion}})?

[pdavies]

Hello there, this PR slipped off my radar but I was reminded of it by this tweet: https://x.com/jskalc/status/1816920900660236370

I've pushed a change to address @halostatue's suggestion. Anything more you need from me here? Keen to get it in if possible!

[pdavies]

Is there any action on me to get this over the line?

[josevalim]

Hi @pdavies, I believe the only blocker is making this fit visually. Perhaps just an alert icon after the version selector is enough? On mouse over we could say "Go to latest version", which will be done on click? Unsure.

[josevalim]

Someone dropped a suggestion on the forum which I quite like:

https://elixirforum.com/t/search-engines-return-old-library-versions/58873/10

What do you think? It is quite subtle but probably enough to portray the meaning. Then the person can click on the select to go to latest. So no additional buttons needed.

[zachdaniel]

Great idea 👌👌👌

[wojtekmach]

Can we go regular color for latest, otherwise orange, i.e. no green? This would be subjectively less busy visually. The downside would be for docs generated with prior ExDoc versions there would be no difference but less of an issue in the long term.

[halostatue]

@josevalim The problem with the colour approach is red-green colour blindness. I think that some sort of iconography or plain text is going to be best and most accessible.

[josevalim]

@halostatue what if we just show yellow/orange if outdated? No need to show it on green if latest.

I am also open to using icons, if there is a good suggestion. But if we don't have one such proposal for now, my suggestion is to ship this and we continue refining it in the future (adding icons, notifications, etc).

[josevalim]

@pdavies, are you ok with someone else carrying this over the finish line or do you want some time? It is your call, it was pending on the ExDoc team decision for sometime anyway. Thanks!

[halostatue]

Simulated deuteranopia

Simulated Deuteranomaly

Simullated Protanopia

Simulated Protanomaly

Simulated Tritanopia

Simulated Tritanopoly

Simulated Monochromacy

Simulated Partial Monochromacy

All of this is with SimDaltonism: https://github.com/michelf/sim-daltonism for macOS.

(I am not colour blind myself, but I have a friend who is.)

[josevalim]

Thank you, those are helpful. Given we only plan to highlight it when it is outdated, we can compare the color of the version with the “Elixir” title in the first example, and it seems it is noticeable in all images. So we can move forward.

although I also I think the color is too subtle overall, even in regular cases without the simulation, so we should definitely have additional mechanisms or icons. Suggestions and mockups are definitely welcome, so we iterate until we find something nice looking and useful.

[halostatue]

Thank you, those are helpful. Given we only plan to highlight it when it is outdated, we can compare the color of the version with the “Elixir” title in the first example, and it seems it is noticeable in all images. So we can move forward.

I think something like this might work:

⏷ v1.17.3
⏷ v1.17.2 ⚠️

is likely to be a better choice — if the warning sign is a popover so that the meaning of that sign can be tapped/clicked (in either mobile or desktop) to see the meaning (something like This is not the current version of the documentation.).

I do worry that it's going to be too subtle, and also think that it would be good to show the version on desktop like we do on mobile if the sidebar is hidden. We could then also use the same hooks that the dropdown is using to append the ⚠️ popover activator to present the same message without showing the sidebar.

Also, here's the simulated protanopia view of the suggestion:

[halostatue]

The warning sign looks like it's going to be pretty stable in terms of display size and style across operating systems and devices, per emojipedia (scrolling required to see the options).

[josevalim]

We should not use the emoji IMO because it is too dissonant. We don’t use them anywhere else in ExDoc UI. We do use Remix icons though, and perhaps the warning one can be used. I believe it is already in the build as we use it for admonition.

[halostatue]

Looking at ones that suggest a warning, I think that spam, alarm-warning, and thunderstorms are the best choices — and they may not be used, but I don't think that's a negative here because this should be seen.

I am sort of partial to the spam one for multiple reasons (it's a hexagon, which goes well with hexdocs; the old versions of the docs when found via search engines are essentially a form of spam).

[josevalim]

We already have alert-line as part of the bundle, so we can probably just use it, and it looks like the emoji:

[pdavies]

@pdavies, are you ok with someone else carrying this over the finish line or do you want some time? It is your call, it was pending on the ExDoc team decision for sometime anyway. Thanks!

Sorry I've not been super responsive! Very happy for someone to carry this over the line as I make no claims about being a UI designer. But if my opinion is worth anything after saying that... we don't want it to be garish, but it has little value if users don't notice it. I share @halostatue's concern that it could end up too subtle. Using the remix icons is a good call (for a start, it's theme-aware), but something needs to provide contrast/colour that the emoji was adding. Everyone will have a different opinion on the right balance and I think I'm partly chickening out so I'm not the person who has to find the right compromise while also ensuring that it's themed, accessible, etc 😅

[josevalim]

Thank you. I think we can make the version number and the remix icon colored in orange/yellow when outdated. At least have that as a starting point. @alisinabh, would you like to pick it up?

[alisinabh]

@josevalim yes sure. Would be happy to do it.

[halostatue]

Thank you. I think we can make the version number and the remix icon colored in orange/yellow when outdated. At least have that as a starting point. @alisinabh, would you like to pick it up?

I would choose yellow over orange as it has higher contrast even with variances of colour blindness.

[josevalim]

Thank you @pdavies for getting the party started! Merged as part of #2012.