docs: add/remove elements for more clarity on the version of the docs you're on #13810
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
added 3 commits
October 24, 2024 14:18
- per in-line comment, this is to remove ambiguity / misleading information, as that number is always set to the latest stable release in GH and _not_ the version of the documentation a user is currently on - as noted in [CNCF Tech Writers Office Hours on Sept 25th](https://docs.google.com/document/d/1roexHTLCrErYjNT2NEoRsVnn_YNbQzZ1gyXNK8hXR4Q/edit?tab=t.0#heading=h.psfvntb79ssg) - use JS here as this is _not_ [overrideable via partial](https://squidfunk.github.io/mkdocs-material/customization/?h=java#overriding-partials): - the `source` partial [uses](https://github.com/squidfunk/mkdocs-material/blob/198a6801fcf687ecb4d22e5c493fdf80427bdd33/src/templates/partials/source.html#L28) a [JS component](https://github.com/squidfunk/mkdocs-material/blob/198a6801fcf687ecb4d22e5c493fdf80427bdd33/src/templates/assets/javascripts/templates/source/index.tsx#L37) - follows [JS customization docs](https://squidfunk.github.io/mkdocs-material/customization/?h=java#additional-javascript) Signed-off-by: Anton Gilgur <agilgur5@gmail.com>
- another indicator of the docs version somewhere - as noted in [CNCF Tech Writers Office Hours on Sept 25th](https://docs.google.com/document/d/1roexHTLCrErYjNT2NEoRsVnn_YNbQzZ1gyXNK8hXR4Q/edit?tab=t.0#heading=h.psfvntb79ssg) - this uses some hacky JS to insert the version based on the URL since there is no other way to configure this in `mkdocs` - versioning is outside of its scope, either via plugins, or in our case, RTD, so can't be done via partial either - organize the JS a bit more into functions at least though Signed-off-by: Anton Gilgur <agilgur5@gmail.com>
- uses the same classes, so use `querySelectorAll` instead - handle positioning of the `versionSpan` differently in the sidenav as it doesn't appear just underneath the logo and instead appeared overlapping the title text - so move it to the right of the logo instead Signed-off-by: Anton Gilgur <agilgur5@gmail.com>
agilgur5
changed the title
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Motivation
In CNCF Tech Docs Office Hours on Sept 25th, a couple of items in the docs stood out as confusing or lacking clarity around versions, including the GH link and a lack of version in the header/logo/home button
Modifications
remove version number from GH link
sourcepartial uses a JS componentadd minor version number underneath the logo in the header (the "home" button)
latest, use "dev" instead, as that is more clear than "latest", per Tech Docs OHmkdocshandle sidenav vs. header on mobile
Verification
Visually inspected. See screenshots:
Before:
Header:
SideNav:
After:
Header:
SideNav:
Future Work
latestand/or non-stablewarning readthedocs/addons#133 (comment) / Make notifications permanently dismissed readthedocs/addons#283