crate
Version chooser: Stop navigation path from `master` to `latest` in certain conditions
About
We discovered an unfortunate navigation path where the version chooser widget renders broken links, which specifically becomes apparent in the appendices/release-notes section of the reference documentation.
Thoughts
This is not much of a concern anywhere else where we use versioned documentation [^1], because documentation layout is pretty stable on those artefacts, so relevant deviances mostly just don't happen.
In this spirit, we think it's applicable to mitigate rendering broken links by applying this specific workaround, even if it introduces a little heuristic based on concrete subject matters.
References
- https://github.com/crate/crate-docs-theme/issues/639
[^1]: Because there wasn't much need, we disabled the version chooser on many other projects anyway today, so all of this applies mostly to the CrateDB reference documentation anyway.
apologies If I'm confused, but don't we want to do the opposite? avoid navigation from latest to master?
Maybe I am confused ;], please help. In this comment by @michaelkremmel, he says (sampling two spots):
-
Origin: https://cratedb.com/docs/crate/reference/en/master/appendices/release-notes/6.1.0.html Problem: https://cratedb.com/docs/crate/reference/en/latest/appendices/release-notes/6.1.0.html
-
Origin: https://cratedb.com/docs/crate/reference/en/master/appendices/release-notes/6.1.1.html Problem: https://cratedb.com/docs/crate/reference/en/latest/appendices/release-notes/6.1.1.html
I've deliberately swapped the display order Origin -> Problem to make it more apparent and easy to follow: Navigate to the "origin" page, use the version chooser, but don't navigate, instead copy the link from the "latest" version slug. Then, use that link 1:1 in another tab to navigate to, and you will enjoy the 404.
If I am not getting it wrong, this outlines a navigation path from master to latest. Please advise if you think I am mixing things up.
I do not think that this is needed at all and just adds complexity.
When I'm reading the master doc, it can always happen that the current page is not available in the latest release. It will happen for any new documentation page we add, such new features.
So just excluding the release notes won't solve it.
Can we close this and also https://github.com/crate/crate-docs-theme/issues/639 please?
