Repository navigation
Docs: cut the v0.8 documentation release and announce it with a banner - #125
Merged
Merged
Conversation
Ibrahim2595
changed the base branch from
fix/versioned-docs-edit-url
to
main
September 24, 2026 19:37
v0.7 was the only released version, so /docs/ served a snapshot taken before the documentation was restructured. The current tree in rossoctl/rossoctl carries the task-based information architecture and the pages added since, and none of it was published. Snapshot the dev docs as 0.8 with `docusaurus docs:version 0.8`, taken from rossoctl/rossoctl@dcd53d8d. The snapshot is byte-identical to that tree: 82 files, `diff -r` clean against the synced docs/. versions.json is written newest-first, and docusaurus.config.ts derives the whole version map from it, so this needs no config change: /docs/* v0.8, labelled "v0.8 (latest)" <- lastVersion /docs/0.7/* v0.7, labelled "v0.7" /docs/dev/* the docs/ folder, labelled "dev" The URL for the latest release stays /docs/ and now resolves to 0.8. v0.7 keeps its content at /docs/0.7/*, rendered from versioned_docs/version-0.7/ in this repository. Readers who follow a /docs/<path> link written against 0.7 land on 0.8 instead, or on a 404 where the restructure renamed the section; that is the intent of a "latest" URL, and 0.7 remains reachable under its own prefix. The v0.8 sidebar snapshot is the current autogenerated one, so it has no wrapping "Documentation" category. v0.7 keeps the wrapper it was cut with. Assisted-By: Claude (Anthropic AI) <noreply@anthropic.com> Signed-off-by: IBRAHIM IBRAHIM <66755652+Ibrahim2595@users.noreply.github.com>
Add a dismissible announcement bar on every page: 🎉 rossoctl 0.8 is here! Explore the updated documentation → "documentation →" links to /docs/, which serves the newest release, so the link follows lastVersion and needs no edit when the next version is cut. The colours are set in src/css/custom.css rather than through the announcementBar `backgroundColor`/`textColor` options, because those render as inline styles and would override the theme tokens. The bar uses the brand red, which is the same value in light and dark, and the link is white because the default link colour is that same red and would be invisible on it. theme-classic's own .announcementBar class sets a white background with equal specificity and is emitted later in the stylesheet, so the three overridden declarations are marked !important; this was confirmed against the built CSS rather than assumed. The `id` is what Docusaurus stores when a reader dismisses the bar, so it carries the version and must change for the next release. Assisted-By: Claude (Anthropic AI) <noreply@anthropic.com> Signed-off-by: IBRAHIM IBRAHIM <66755652+Ibrahim2595@users.noreply.github.com>
Ibrahim2595
force-pushed
the
docs/cut-v0.8-release
branch
from
September 24, 2026 19:48
ed0c2fd to
028983a
Compare
✅ Deploy Preview for animated-crumble-fb8862 ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
This file contains hidden or 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
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.
What & why
v0.7 was the only released version, so
/docs/served a snapshot taken before the documentationwas restructured. The current tree in
rossoctl/rossoctlcarries the task-based informationarchitecture and everything added since, and none of it was published.
This cuts v0.8 from the current
devtree, makes it the latest, and announces it on the site.What changed
1.
Docs: cut the v0.8 documentation releasedocusaurus docs:version 0.8, snapshottingrossoctl/rossoctl@dcd53d8d(the merge of #2583).versioned_docs/version-0.8/— 82 files, byte-identical to the synced dev tree (diff -rclean).versioned_sidebars/version-0.8-sidebars.json— the current autogenerated sidebar, so v0.8 has nowrapping "Documentation" category. v0.7 keeps the wrapper it was cut with.
versions.json— now["0.8", "0.7"], newest first.No
docusaurus.config.tschange was needed for the version map. It already derives everythingfrom
versions.json, including the(latest)label,lastVersion, and the dropdown order. Thatdesign held up exactly as documented in the file.
2.
Feat: announce the 0.8 release with a bannerA dismissible bar on every page: 🎉 rossoctl 0.8 is here! Explore the updated documentation →
documentation →links to/docs/, which serveslastVersion, so it follows the latest releasewithout an edit next time. Colours live in
src/css/custom.css, not in theannouncementBarbackgroundColor/textColoroptions, because those render as inline styles and would override thetheme tokens.
Resulting routes
/docs/*versioned_docs/version-0.8/in this repo/docs/0.7/*versioned_docs/version-0.7/in this repo/docs/dev/*rossoctl/rossoctl:docs/, synced at build time/docs/points only at the newest release, and v0.7 keeps its content under its own/0.7prefix.A
/docs/<path>link written against 0.7 now lands on 0.8, or 404s where the restructure renamed thesection — that is the intent of a "latest" URL, and 0.7 stays reachable at
/docs/0.7/<path>.Verification
Production build (
npm run sync-docs && npm run build): success, no errors, no new warnings.npx tsc --noEmit: clean.Version dropdown, read out of the built HTML:
v0.8 (latest)/docs/v0.7/docs/0.7/overview/what-isdev/docs/dev/The navbar renders
v0.8 (latest)as the active version at/docs/.Edit links, every rendered link mapped back to a file and checked for existence:
versioned_docs/version-0.8/…versioned_docs/version-0.7/…rossoctl/rossoctl→docs/…The new version picked up correct links with no extra work, which is the point of #124's callback.
Banner, parsed out of the built HTML rather than eyeballed:
🎉 rossoctl 0.8 is here! Explore the updated documentation →documentation →→href="/docs/"/contributing/CSS precedence was checked in the built stylesheet, not assumed: our
.theme-announcement-barrule is emitted at offset 339796 and theme-classic's
.announcementBar_*at 352262. The theme's rulecomes later at equal specificity, so it would have won; that is why the three conflicting
declarations carry
!important.Acceptance tier
Assisted-By: Claude Code