Documenter.jl: Add "this version is outdated" notice to versions other than latest

[christopher-dG]

A lot of people have noticed that search engines tend to serve old versions of Julia documentation as well as package docs. Oftentimes, people don't actually realize they're looking at an old version. Some other doc services will display a notice along the lines of "this version is outdated, click here to go to this page in the current version" when displaying old documentation. Could we do something like that?

Here's an example from the Rust ecosystem:

[fredrikekre]

I guess it has to be a script or something that you run on old docs?

[mortenpi]

This wouldn't help with existing deployed documentation, but we could do this going forward at least. On page load, the version selector lists all the versions, so you can check if the current one is the latest one.

[cdsousa]

I think something like the CMake warning banner is very useful:

[eirikbrandsaas]

I support this so much, and I like @cdsousa example.

It's happening so often that I google something, end up in the two-year-old DataFrames documentation without realizing it, and then spend 30 minutes reading outdated docs that with commands that no longer work.

[fredrikekre]

Prototype here: https://fredrikekre.github.io/Literate.jl/v2.6/

Edit: Since I am about to update it, here is the first iteration

[eirikbrandsaas]

Prototype here: https://fredrikekre.github.io/Literate.jl/v2.6/

Big improvement. For visibility, I think it would be better to put it as a banner like CMake or potentially just below the search box.

In the spirit of minimalism: `` or select the appropriate version in the drop-down menu below.'' isn't really necessary: I assume very few people are purposefully using older documentation and a) that subset has used Julia and read the documentation before and b) it's easy to understand where to find the other version.

[christopher-dG]

Awesome! I would recommend using the Julia logo's "inner" red colour with lower opacity to make the text more readable.

Also: This documents and old version -> This documents an old version

[fredrikekre]

For visibility, I think it would be better to put it as a banner like CMake or potentially just below the search box.

Yea maybe, but that requires more CSS than I know so.... I also kinda liked that it is next to the version selector but perhaps it doesn't matter.

Awesome! I would recommend using the Julia logo's "inner" red colour with lower opacity to make the text more readable.

Yea probably, although the logo doesn't have inner colors anymore. (Can of course use that color for this.)

[fredrikekre]

Try 2: https://fredrikekre.github.io/Literate.jl/v2.5/

[eirikbrandsaas]

Try 2: https://fredrikekre.github.io/Literate.jl/v2.5/

:heart_eyes:

[ufechner7]

Please merge this! It cost me so much time to read outdated documentation.

[fredrikekre]

Perhaps we can include @pfitzseb s https://gist.github.com/pfitzseb/4b910449e21b51fed4b4a2a7c20912ff ?

[pfitzseb]

See https://github.com/JuliaData/DataFrames.jl/pull/2760 for what that script does. I'm now also adding a <meta content="noindex" name="robots"/> tag to discourage search engines from picking up outdated docs.

Might make sense to add (something like) this to Documenter's deploy script.

[fredrikekre]

Might make sense to add (something like) this to Documenter's deploy script.

It shouldn't be necessary I think (well, to add it to past releases). Can't the relevant JS code just detect the latest version from the versions.js file? That is what I did in the examples above IIRC.

[pfitzseb]

Ah, that makes a lot of sense :)