Skip to content

fix: version selector and upgrade Docusaurus to 3.9.2#840

Merged
Erik Osterman (Cloud Posse) (osterman) merged 4 commits into
masterfrom
osterman/fix-version-selector
Jan 7, 2026
Merged

fix: version selector and upgrade Docusaurus to 3.9.2#840
Erik Osterman (Cloud Posse) (osterman) merged 4 commits into
masterfrom
osterman/fix-version-selector

Conversation

@osterman
Copy link
Copy Markdown
Member

@osterman Erik Osterman (Cloud Posse) (osterman) commented Dec 30, 2025 •
edited
Loading

Summary

  • Fixed version dropdown to show currently viewed version (e.g., "v1") instead of always showing "Latest"
  • Upgraded Docusaurus from 3.4.0 to 3.9.2
  • Fixed all swizzled components for new Docusaurus API
  • Fixed navbar links to preserve version context
  • Improved version banner and badge UI

Changes

Version Dropdown Fix

  • Swizzled DocsVersionDropdownNavbarItem component to detect version from URL path
  • Works around Docusaurus bug where dropdown uses "preferred version" from localStorage instead of actual viewed version
  • Dropdown now correctly shows "v1" when viewing v1 docs and "Latest" when viewing current docs

Navbar Version-Sticky Links

  • Changed navbar items (Learn, Reference, Community, Support) from to: '/path' to type: 'doc' with docId
  • These links now preserve version context - clicking "Learn" while on v1 docs goes to /v1/learn/ instead of /learn/

Docusaurus Upgrade (3.4.0 → 3.9.2)

  • Updated all @docusaurus/* packages to 3.9.2
  • This fixes sidebar navigation to preserve version context

API Migration

Updated import paths in swizzled components from @docusaurus/theme-common/internal to @docusaurus/plugin-content-docs/client:

  • DocsVersionDropdownNavbarItem - added useHistorySelector for URL detection
  • DocVersionBanner - useDocsVersion hook
  • DocVersionBadge - useDocsVersion hook
  • DocCard - findFirstSidebarItemLink, useDocById hooks
  • CategoryList - useDocsSidebar, useDocById hooks

DocVersionBanner Fix

  • Fixed latest version detection to check both versionMetadata.isLast and versionMetadata.version === 'current'
  • Latest/current version now shows green "tip" admonition (was incorrectly showing yellow warning)
  • Fixed internal links to use versioned paths (e.g., /v1/resources/version-identification/ when on v1)

UI Improvements

  • Fixed version badge vertical alignment in breadcrumbs container
  • Added responsive behavior: sponsor button hides on screens < 996px width
  • Added margin-bottom: 0.8rem to version badge

Test Plan

  • Version dropdown shows "v1" when viewing v1 docs
  • Version dropdown shows "Latest" when viewing current/latest docs
  • Navbar links preserve version (clicking Learn on v1 goes to /v1/learn/)
  • Sidebar links preserve version (all sidebar links on v1 stay in /v1/...)
  • DocVersionBanner shows green "tip" on latest docs
  • DocVersionBanner shows yellow "warning" on v1 docs
  • DocVersionBanner links go to versioned pages
  • Version badge is vertically aligned with breadcrumbs
  • Sponsor button hidden on mobile/tablet screens
  • Build completes without errors

🤖 Generated with Claude Code

@osterman Erik Osterman (Cloud Posse) (osterman) added the no-release Do not create a new release (wait for additional code changes) label Dec 30, 2025
@osterman Erik Osterman (Cloud Posse) (osterman) changed the title fix: display current version in navbar dropdown fix: version selector and upgrade Docusaurus to 3.9.2 Dec 30, 2025
@osterman @claude
fix: display current version in navbar dropdown instead of "Latest"
5df9c48 
Swizzle DocsVersionDropdownNavbarItem component to detect the version
from the URL path rather than relying on activeDocContext.activeVersion,
which was unreliable. Now the dropdown correctly shows "v1" when viewing
v1 docs and "Latest" when viewing current docs.

🤖 Generated with Claude Code

Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>
@osterman @claude
feat: upgrade Docusaurus to 3.9.2 and fix version-related components
b949a90 
- Upgrade Docusaurus from 3.4.0 to 3.9.2
- Update swizzled components to use new API imports from
  @docusaurus/plugin-content-docs/client instead of
  @docusaurus/theme-common/internal
- Fix DocVersionBanner to show green tip for latest/current version
- Fix version badge vertical alignment in breadcrumbs
- Hide sponsor button on smaller screens (< 996px)
- Update DocsVersionDropdownNavbarItem for new Docusaurus 3.9 API

🤖 Generated with Claude Code

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@osterman @claude
fix: navbar links preserve version context
96deeae 
- Change navbar items (Learn, Reference, Community, Support) from
  `to: '/path'` to `type: 'doc'` with `docId` to preserve version
- Fix DocVersionBanner internal links to use versioned paths
- Minor footer link trailing slash consistency

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@osterman @claude
fix: add truncation markers to blog posts
6bf9d92 
Add <!--truncate--> markers after the intro section in all blog posts
that were missing them to eliminate Docusaurus build warnings.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@osterman Erik Osterman (Cloud Posse) (osterman) merged commit 8354b1e into master Jan 7, 2026
3 checks passed
@osterman Erik Osterman (Cloud Posse) (osterman) deleted the osterman/fix-version-selector branch January 7, 2026 16:24
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

no-release Do not create a new release (wait for additional code changes)

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@osterman