docs: Add version switcher - Make v0.5.x the default (Latest)

[corylanou]

Add Documentation Version Switcher

Summary

Implements version switcher for Litestream documentation to support both v0.3.13 and v0.5.x versions. This addresses issue #92 by providing clear version guidance and making v0.5.x the new default "Latest" version.

Changes

Version Terminology

• v0.5.x (Latest) - Actively maintained with new features and bug fixes (NEW DEFAULT)
• v0.3.13 (Previous) - Critical fixes only

Implementation Details

• ✅ Version banner component displays prominently at top of all pages
• ✅ Branch-based versioning (industry standard approach)
• ✅ No force pushes required for future releases
• ✅ Both versions build successfully and independently

Branches

• docs-v0.5 → Latest version (will become new main)
• docs-v0.3 → Previous version (archived, critical fixes only)
• main → Will point to latest (v0.5 after merge)

🚨 Required: Netlify Configuration (2 minutes)

Ben - You need to enable branch deploys in the Netlify dashboard before merging this PR.

Steps:

1. Go to Netlify dashboard → litestream.io site
2. Navigate to: Site settings → Build & deploy → Continuous deployment → Branches
3. Change from "Deploy only production branch" to "Deploy all branches"
4. Click Save

This enables Netlify to automatically deploy the docs-v0.3 branch so users can access previous version docs.

What This Does:

• Netlify will auto-generate a URL like: docs-v0-3--litestream.netlify.app
• After enabling, reply here with the generated URL
• I'll update the version banner link and push a follow-up commit

Optional: Custom Domain

If you want a cleaner URL (recommended):

• Add custom subdomain: v0-3.litestream.io → points to docs-v0-3 branch deploy

Deployment Plan (Zero Downtime)

Current State

• Main site (litestream.io) → deploys from main branch → v0.3.13 content

After Merge (Automatic)

1. This PR merges docs-v0.5 → main
2. Netlify automatically deploys updated main
3. Main site (litestream.io) → now shows v0.5.x as Latest
4. Branch deploy (docs-v0-3--litestream.netlify.app) → shows v0.3.13 with "Previous" label

Result

• ✅ Zero downtime
• ✅ v0.5.x becomes the default at litestream.io
• ✅ v0.3.13 remains accessible via branch URL
• ✅ Version switcher links work between both versions

Future Version Releases (v0.6, v0.7, etc.)

NO dashboard changes needed! Just:

1. Create new branch docs-v0.6
2. Merge to main
3. Done - Netlify auto-deploys

Previous versions remain accessible via branch URLs automatically.

Testing

✅ Local builds verified:

• docs-v0.3: 60 pages (no NATS, MCP, LTX)
• docs-v0.5: 63 pages (includes new features)

Local Testing Instructions

Option 1: View One Version at a Time (Simple)

View v0.5 (Latest):

git checkout docs-v0.5
npm run start
# Visit http://localhost:1313

View v0.3 (Previous):

# Stop the server (Ctrl+C), then:
git checkout docs-v0.3
npm run start
# Visit http://localhost:1313

You'll see the version banner at the top with appropriate styling and labels.

Option 2: View Both Versions Side-by-Side (Advanced)

Uses git worktrees to run both versions simultaneously in isolated directories:

Terminal 1 - v0.5 (Latest):

git checkout docs-v0.5
npm run start
# Visit http://localhost:1313

Terminal 2 - v0.3 (Previous) in separate worktree:

# Create worktree for v0.3 in parallel directory
git worktree add ../litestream.io-v0.3 docs-v0.3
cd ../litestream.io-v0.3
npm install
npm run start -- --port 1314
# Visit http://localhost:1314

Now you can compare both versions side-by-side in different browser tabs!

Cleanup when done:

cd ../litestream.io
git worktree remove ../litestream.io-v0.3

Note: Version switcher links will show placeholder URLs until Netlify branch deploys are enabled. The banner styling and version labels will work correctly.

Screenshots

Version banner on v0.5 (Latest):

┌─────────────────────────────────────────────────────────────────┐
│ v0.5.x - Latest - Actively maintained with new features and    │
│ bug fixes | View v0.3.13 (Previous)                            │
└─────────────────────────────────────────────────────────────────┘

Version banner on v0.3 (Previous):

┌─────────────────────────────────────────────────────────────────┐
│ ⚠️ v0.3.13 - Previous version - Critical fixes only |          │
│ View v0.5.x (Latest)                                           │
└─────────────────────────────────────────────────────────────────┘

Checklist for Ben

• Enable "Deploy all branches" in Netlify dashboard
• Wait for docs-v0-3 branch to build (~2 min)
• Reply with generated URL (e.g., docs-v0-3--litestream.netlify.app)
• (Optional) Add custom domain v0-3.litestream.io
• Verify version switcher links work
• Merge this PR → v0.5 becomes default!

Resolves

Closes #92