Doc Versioning UX
Ship documentation that respects your users' context. Versioned docs with zero-friction switching, permalink stability, and automated migration callouts.
Semantic URL structure
Route docs under /docs/v2/ with a canonical latest redirect. Never break a permalink.
Version selector dropdown
Persistent top-bar picker showing current version with a subtle violet badge. List all maintained versions; mark deprecated ones with a muted style.
Cross-version banners
When a page exists in a newer version, show a non-blocking gradient banner: “A newer version of this page is available.” Link directly to the equivalent path.
Deprecation timeline
Publish a public version-support matrix. Auto-inject a dismissible notice 90 days before EOL. Never hard-redirect stale URLs without user consent.
Quick implementation
Use Next.js catch-all routes with a [version] param. Resolve content from a versioned directory or CMS collection. Middleware sets a cookie so the selector persists across navigation.