Vcluster Docs Archiver

vCluster Documentation Archiver

Overview

Archive End-of-Life (EOL) vCluster or Platform documentation versions to standalone Netlify deployments. Each EOL version gets its own branch that never merges to main.

When to Use

• User asks to archive a vCluster or Platform version
• User mentions EOL documentation, branch archiving, or version archiving
• Working in /home/decoder/loft/vcluster-docs with archiving tasks
• User encounters broken links during version archiving

Quick Start

Step 1: Setup Archive Branch

# Create branch (use correct naming: vcluster-v0.22 or platform-v4.2)
git checkout -b vcluster-v0.22

# Verify version exists
scripts/verify_version.sh 0.22.0

Step 2: Configure Docusaurus

Edit docusaurus.config.js:

• Set lastVersion: "0.22.0" (actual version)
• Set onlyIncludeVersions: ["0.22.0"] (only this version)
• Set noIndex: true at top level (prevent search engine indexing)
• Set onBrokenLinks: "warn" (cross-section mismatches are expected in archives)
• Update main docs label to match version
• Add archive announcement bar (yellow warning, not closeable, links to latest docs)

Edit src/config/versionConfig.js:

• Empty both hidden arrays: vclusterHiddenVersions = [], platformHiddenVersions = []

Edit src/theme/DocSidebar/Desktop/Content/index.js:

• Set dropdownItemsAfter={[]} (empty dropdown)

See references/docusaurus-config.md and references/platform-archiving.md (section 4b) for detailed configuration.

Step 2b: Strip Version Prefix from Internal Links

When a version becomes lastVersion, Docusaurus serves it without the version segment. Strip all internal links that include the version prefix:

# For platform archives (e.g., 4.5.0)
find platform_versioned_docs/version-4.5.0 -name "*.mdx" \
  -exec sed -i 's|/docs/platform/4.5.0/|/docs/platform/|g' {} +

# For vCluster archives (e.g., 0.28.0)
find vcluster_versioned_docs/version-0.28.0 -name "*.mdx" \
  -exec sed -i 's|/docs/vcluster/0.28.0/|/docs/vcluster/|g' {} +

Expect 50-70+ replacements for platform archives. Verify with grep afterward.

See references/platform-archiving.md (section 4c) for details.

Step 3: Fix Broken Links

# Clear cache first
scripts/clear_cache.sh

# Auto-fix common patterns
scripts/fix_mdx_extensions.sh vcluster_versioned_docs/version-0.22.0
scripts/fix_site_imports.sh vcluster_versioned_docs/version-0.22.0

# Build and fix remaining errors
npm run build

Efficient debugging method: See references/link-resolution-guide.md

Step 4: Configure Netlify & Deploy

⚠️ Netlify branch deploys require MANUAL configuration

1. User configures in Netlify dashboard:

   • Site settings → Build & deploy → Branches and deploy contexts
   • Add branch name (e.g., vcluster-v0.22) to "Branch deploys"

2. After configuration, trigger build:

   git commit --allow-empty -m "chore: trigger netlify build"
   git push origin vcluster-v0.22
   

3. Verify deployment:

   curl -s -o /dev/null -w "%{http_code}" "https://vcluster-v0-22--vcluster-docs-site.netlify.app/docs/vcluster/"
   

Step 5: Update Main Branch

⚠️ IMPORTANT: Stage changes, do NOT commit (user commits manually)

git checkout main

# Update dropdown in src/theme/DocSidebar/Desktop/Content/index.js
# Remove version from docusaurus.config.js onlyIncludeVersions
# Delete versioned folder: rm -rf vcluster_versioned_docs/version-0.22.0

git status  # Show staged changes to user

Step 5b: Add Long-Form Redirect in vcluster-docs (REQUIRED)

This is a separate redirect layer from Step 6 — easy to miss because it lives in this repo, not vcluster.com. Deleting the versioned folder in Step 5 removes the long-form /docs/vcluster/X.Y.Z/* URLs from the build; without this redirect, they 404 instead of falling back to latest.

In this repo's netlify.toml, add a row to the "Removed vCluster versions — redirect to latest" block:

[[redirects]]
  from = "/docs/vcluster/0.22.0/*"
  to = "/docs/vcluster/:splat"
  status = 301

Keep the block in ascending version order alongside the existing rows.

Step 6: Add Redirects (REQUIRED)

In /home/decoder/loft/vcluster.com/themes/loft/static/_redirects:

# v0.22 Docs Site (EOL version with dedicated standalone site)
/docs/v0.22         https://vcluster-v0-22--vcluster-docs-site.netlify.app/docs/vcluster/introduction/what-are-virtual-clusters/   302!
/docs/v0.22/*       https://vcluster-v0-22--vcluster-docs-site.netlify.app/docs/vcluster/:splat   302!

⚠️ MERGE ORDER IS CRITICAL:

1. Merge redirects PR (vcluster.com) FIRST
2. Then merge dropdown PR (vcluster-docs)

If dropdown merges first, users clicking EOL links will hit 404s.

User must commit vcluster.com changes

Critical Rules

🚨 NEVER perform git operations - NO commits, NO PRs, NO branches, NO pushes

• Platform onlyIncludeVersions MUST NOT be empty - use ["X.X.X"]
• NEVER set includeCurrentVersion: false - breaks partials
• Use LATEST vCluster version with Platform archives (0.32.0, not 0.25.0)
• Clear cache after major fixes: scripts/clear_cache.sh

See references/critical-rules.md for complete list.

Resources

scripts/

• verify_version.sh - Check if versioned docs exist
• fix_mdx_extensions.sh - Remove .mdx from links
• fix_site_imports.sh - Replace @site imports
• clear_cache.sh - Clear Docusaurus caches
• find_feature_location.sh - Find version-specific features

references/

• critical-rules.md - Complete never-do and always-do rules
• link-resolution-guide.md - Link types and .mdx extension rules
• platform-archiving.md - Platform-specific workflow
• platform-4.2-example.md - Real-world example with mistakes
• complete-checklist.md - Full step-by-step checklist
• common-issues.md - Troubleshooting guide

Step 7: Announce (Optional)

Slack announcement template:

*vCluster docs: EOL version archiving*

We archived vCluster vX.XX documentation to standalone Netlify branch deploys.

*Why:* The main docs build includes all active versions. As we add new versions, the build size grows and eventually exceeds Netlify's memory limits. Archiving EOL versions to separate branches keeps the main build healthy.

*What changed:*
- vX.XX docs removed from main branch
- Version now lives on its own branch (`vcluster-vX.XX`)
- Added to EOL dropdown in version selector
- Redirects ensure `vcluster.com/docs/vX.XX` still works

*Impact:* None. Users accessing EOL docs via the dropdown or direct URLs will be redirected to the archived deployments. No action required.

Quick Reference

Final Checklist (Copy-Paste for User)

When archiving is complete, guide the user with these steps:

Archive Complete! Final steps:

□ 1. Configure Netlify branch deploys (manual in dashboard)
   - Site settings → Build & deploy → Branches and deploy contexts
   - Add: vcluster-vX.XX (or platform-vX.X)

□ 2. Trigger builds (empty commits if needed)
   - git checkout vcluster-vX.XX && git commit --allow-empty -m "chore: trigger netlify build" && git push

□ 3. Verify deployments work
   - https://vcluster-v0-XX--vcluster-docs-site.netlify.app/docs/vcluster/

□ 4. MERGE ORDER (critical!):
   a. FIRST: Merge redirects PR (vcluster.com)
   b. THEN: Merge dropdown PR (vcluster-docs) — confirm it includes the
      netlify.toml row from Step 5b, not just the dropdown/version removal

□ 5. Post to Slack (optional)
   - Use template from Step 7

□ 6. Verify production
   - Check vcluster.com/docs/vX.XX redirects correctly
   - Check vcluster.com/docs/vcluster/X.Y.Z/* (long-form URL) redirects to latest
   - Check dropdown shows new EOL version