Adding a banner for non-recent documentation versions

[JulioV]

• [ x] I've read the contribution guidelines and agree with them

I want to suggest an idea and checked that ...

• [ x] ... to my best knowledge, my idea wouldn't break something for other users
• [ x] ... the documentation does not mention anything about my idea
• [ x] ... there are no open or closed issues that are related to my idea

Description

Create a banner at the top of each page on old versions of the docs (when managed by mike) that point to the latest (most recent) version

Use Cases

Whenever a user lands on an old docs page, they can be redirected to the most recent version like readthedocs

Screenshots / Mockups

There are some suggestions in this issue jimporter/mike#26 (see screenshot below)

There could be a flag to activate this feature on every version (and its aliases) except for the most recent one based on mike's versions.json indexes:

[
  {"version": "1.0", "title": "1.0.1", "aliases": ["latest"]},
  {"version": "0.9", "title": "0.9", "aliases": []}
]

The actual content and look and feel could be customizable like the announcement section of the theme

[squidfunk]

Thanks for suggesting! I agree that this is a good idea which we should investigate. However, from the top of my head, there may be problems with content shift due to the fact that the mike integration is all-JavaScript, which means that the version selector is rendered after the initial load. Thus, the notice will be displayed after the initial render, shifting the content downwards, which is penalized by reports like Lighthouse and in general is not a good idea.

Material for MkDocs painstakingly tries to minimize content shift and it does a very good job at that, so a possible solution for displaying a banner should not introduce this problem.

[squidfunk]

I converted this issue to a discussion, as I'd like to get some feedback before we decide whether and how we should implement it. Also note that there are problems with content shift that would need to be addressed somehow, as I stated in my last comment.

[miguno]

Adding my +1 to this feature suggestion.

Material for MkDocs painstakingly tries to minimize content shift and it does a very good job at that, so a possible solution for displaying a banner should not introduce this problem.

This would be great indeed for UX.

That said, in my case it's much more important to notify users that they are looking at an old version of the content, even if this required content shifting for older versions. As I understand, no shift would happen for the 'latest' version this shift shouldn't happen, and (in my case) the great majority of traffic is for the latest version.

[JulioV]

I agree with @miguno, a small content shift is preferable to users browsing the wrong documentation version.

Is it possible to achieve no shift? One approach would be to have mike override the announce block on old versions (folders) during a mike deploy --push but I don't think is something they would want to integrate.

A popup would be another alternative but people dislike those more than content shifts I'd guess.

[JulioV]

1 and 2 sound good.

Not sure about 3, people tend to completely ignore things at the bottom, especially if the page is long. Could we pre-render a div block at the top containing the hidden warning span only when extra: version: method: mike and un-hide the warning span when the version alias is not latest?

[squidfunk]

Regarding 3, it would be fixed to the viewport, not the bottom of the document. However, CSS can be overridden and the banner can be positioned as desired by the author. Material for MkDocs would only provide a sane default.

[JulioV]

ah got it, that makes sense and works for me

[miguno]

Yes to 1 and 2.

Comment for 2:

The banner will be rendered with JavaScript when the version selector is rendered and a non-latest version is detected. The version alias for the latest version will be latest. If another version is active, the notice is rendered

mike lets you set a default version with:

$ mike set-default [version-or-alias]

If possible, this should be honored. If not possible, then 'latest' seems like a good default to me.

Yes to 3 (viewport, not bottom of the document).

[squidfunk]

Heads-up: I'm close to finishing a solution with the following properties:

1. Banner is rendered at the top, above the header, it disappears when scrolling down (similar to announcement bar)
2. It will only shift the content the first time the page is loaded
3. Every subsequent load does not incur content shift
4. The "latest" tag is configurable via mkdocs.yml
5. The content can be freely defined (similar to announcement bar)

It doesn't use any translations, which means the author has to use theme extension to define it, but given the many different ways that those banners may look, I think it's the best approach. In the end, it boils down to defining a single template block:

{% block outdated %}
  You're not viewing the latest version of PRODUCT X.
  <a href="{{ config.site_url }}/{{ config.extra.version.latest }}">
    Click here to go to latest.
  </a>
{% endblock %}

It would be perfect to fetch the latest version tag from mike, but since mike is run on-top of mkdocs, that's not possible. However, the latest version tag should rarely change, so this shouldn't be a problem.

Also, I've discontinued following the "stick to bottom" solution, because it would steal too much space and might introduce problems with the copy to clipboard dialog or the back-to-top button.

[squidfunk]

The version warning feature is now available!

[JulioV]

thanks a lot!

[miguno]

This looks great, thank you!