Add support for Semantic Versioning to the Version Warning

[SaltyAimbOtter]

Contribution guidelines

• I've read the contribution guidelines and wholeheartedly agree

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

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

Description

The version warning should be able to correctly inform the user about outdated versions if the semantic versioning version format is used.

The current behaviour is like this:
Green = Correctly shows no warning (latest)
Red = Shows no warning although it should
Light Green = Correctly shows a warning

Mike does claim that it is made for two digit version only. However, it also claims that it is "flexible". In our project, we never had any problems using semantic versioning with mike. I'm sure it's a common use case considering that semantic versioning is quite popular.

In addition to that a dedicated banner for development versions would be useful:
We have one RELEASE (1.2.3) doc version and one DEV doc version (e.g. 2.0.0-DEV). Additionally there are many old docs versions (e.g. 1.2.2, 1.2.1 etc.).
We would like to show one variant of the warning banner in the docs of legacy versions and another in the development docs.
This could be attached to aliases:

Mike Alias	Banner
latest	No Banner
development	Banner Variant 1
none	Banner Variant 2

Where Banner Variant 1 would say something like: You are viewing the docs for the development version! Be careful or use the latest release!
And Banner Variant 2 would say something like: You are viewing outdated docs and will recieve no support! Update to the latest release!

The amount of version qualifiers might differ between projects though. So this should be customizable. I'm not sure if and how this could be implemented considering the current implementation works with theme overrides.

Use Cases

Many users probably release one documentation version together with a software release. Since semantic versioning is very popular this should affect a large part of the user base.

Screenshots / Mockups

No response

[squidfunk]

Thanks for suggesting! This is a reasonable change request, but I'm not sure if it benefits a lot of users or is too specific to be included in core. It can definitely be pulled off with some JavaScript and theme extension (which is necessary for the announcement bar anyway). Let's let this suggestion sit here for a while and see if other users find it interesting as well 😊

[SaltyAimbOtter]

The members of my project had a discussion which changed our view about this topic. These are our conclusions:

When semantic versioning is followed correctly, there should never be a reason to change the docs for a patch release.
Therefore, two digit docs make sense even for projects with three digit versions. This also has a few beneficical side-effects:

• Less visual clutter for the user as the version dropdown has less content.
• Less versions on the gh-pages branch
  • Reduces cost if Git LFS / GitHub's paid service is in use.
  • Reduces time spend on up- / downloading doc-artifacts during GitHub Action runs (project specific).

As a result we have adjusted our workflow to only have two digit doc-versions.

So now our only additional requirement is that we don't want to show an "invalid" version warning in docs of the development branch . Therefore we have opened #4976 that introduces the ability to define multiple aliases that hide the version warning.

[squidfunk]

Fixed in b257235. Also see #4976 (comment).

[squidfunk]

Released as part of 9.0.13.