// Archive End-of-Life vCluster documentation versions. Use this skill when creating EOL documentation branches for vCluster or Platform versions. Handles branch creation, Docusaurus configuration, link fixing, Netlify deployment, and main branch updates.
Platform Documentation Release Skill
vCluster Documentation Release Skill
Write and edit vCluster Docusaurus documentation. Use this skill when working with .mdx or .md files in the vcluster-docs repository. Handles vale linting, partials discovery, link validation, versioned docs, and release processes.
Manages the Kubernetes compatibility matrix data and React component. Use when adding/removing K8s versions, updating conformance test results, or documenting known issues.
Generate MDX config reference partials from vCluster JSON schema. Use when automation is skipped for alpha releases or when manually refreshing config docs.
Upgrades Docusaurus to latest version in vCluster documentation. Use when upgrading Docusaurus packages from older to newer versions. Handles package updates, compatibility fixes, testing, and rollback procedures.
| name | vcluster-docs-archiver |
| description | Archive End-of-Life vCluster documentation versions. Use this skill when creating EOL documentation branches for vCluster or Platform versions. Handles branch creation, Docusaurus configuration, link fixing, Netlify deployment, and main branch updates. |
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.
/home/decoder/loft/vcluster-docs with archiving tasks# 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
Edit docusaurus.config.js:
lastVersion: "0.22.0" (actual version)onlyIncludeVersions: ["0.22.0"] (only this version)noIndex: true at top level (prevent search engine indexing)onBrokenLinks: "warn" (cross-section mismatches are expected in archives)Edit src/config/versionConfig.js:
vclusterHiddenVersions = [], platformHiddenVersions = []Edit src/theme/DocSidebar/Desktop/Content/index.js:
dropdownItemsAfter={[]} (empty dropdown)See references/docusaurus-config.md and references/platform-archiving.md (section 4b) for detailed configuration.
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.
# 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
⚠️ Netlify branch deploys require MANUAL configuration
User configures in Netlify dashboard:
vcluster-v0.22) to "Branch deploys"After configuration, trigger build:
git commit --allow-empty -m "chore: trigger netlify build"
git push origin vcluster-v0.22
Verify deployment:
curl -s -o /dev/null -w "%{http_code}" "https://vcluster-v0-22--vcluster-docs-site.netlify.app/docs/vcluster/"
⚠️ 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
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:
If dropdown merges first, users clicking EOL links will hit 404s.
User must commit vcluster.com changes
🚨 NEVER perform git operations - NO commits, NO PRs, NO branches, NO pushes
onlyIncludeVersions MUST NOT be empty - use ["X.X.X"]includeCurrentVersion: false - breaks partialsscripts/clear_cache.shSee references/critical-rules.md for complete list.
verify_version.sh - Check if versioned docs existfix_mdx_extensions.sh - Remove .mdx from linksfix_site_imports.sh - Replace @site importsclear_cache.sh - Clear Docusaurus cachesfind_feature_location.sh - Find version-specific featurescritical-rules.md - Complete never-do and always-do ruleslink-resolution-guide.md - Link types and .mdx extension rulesplatform-archiving.md - Platform-specific workflowplatform-4.2-example.md - Real-world example with mistakescomplete-checklist.md - Full step-by-step checklistcommon-issues.md - Troubleshooting guideSlack 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.
| Issue | Solution |
|---|---|
| Broken links | references/link-resolution-guide.md |
| Platform version | references/platform-archiving.md |
| Config errors | references/docusaurus-config.md |
| Real example | references/platform-4.2-example.md |
| Netlify setup | Configure in Netlify dashboard, then empty commit |
| Merge order | Redirects (vcluster.com) FIRST, then dropdown (vcluster-docs) |
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)
□ 5. Post to Slack (optional)
- Use template from Step 7
□ 6. Verify production
- Check vcluster.com/docs/vX.XX redirects correctly
- Check dropdown shows new EOL version