// 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.
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.
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.
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.
| name | docusaurus-upgrader |
| description | 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. |
Upgrades Docusaurus in vCluster documentation repository with safe workflows, testing procedures, and rollback capability.
/home/decoder/loft/vcluster-docs with upgrade tasks# Check current versions
scripts/check_versions.sh
cat package.json | grep "@docusaurus"
Note current versions for rollback if needed.
# Upgrade to specific version (e.g., 3.7.0)
npm install @docusaurus/core@3.7.0 @docusaurus/preset-classic@3.7.0 \
@docusaurus/plugin-content-docs@3.7.0 \
@docusaurus/plugin-content-blog@3.7.0 \
@docusaurus/theme-classic@3.7.0
# Or to latest
npm update @docusaurus/core @docusaurus/preset-classic
Critical: Upgrade ALL Docusaurus packages to same version.
See references/upgrade-guide.md for complete package list.
# Essential step - prevents dependency conflicts
npm run clear
rm -rf node_modules package-lock.json
npm install
Never skip this step!
Check for breaking changes:
# Review official changelog
# https://docusaurus.io/changelog
# Test dev server
npm start
Common fixes needed:
See references/common-issues.md for known compatibility fixes.
Development test:
npm start
# Verify: pages load, navigation works, search works
Production build test:
scripts/test_build.sh
# Or manually:
npm run build && npm run serve
Checklist:
See references/testing-checklist.md for comprehensive checks.
If upgrade causes issues:
# Automated
scripts/rollback.sh
# Manual
git checkout package.json docusaurus.config.js src/theme/
rm -rf node_modules package-lock.json
npm install
npm run clear && rm -rf node_modules package-lock.json && npm install| Issue | Solution |
|---|---|
| CSS styling broken | Check for class name changes |
| Components not working | Check theme API changes |
| MDX rendering issues | Check MDX 3 compatibility |
| Search broken | Verify Algolia config |
| Build fails | Check deprecated API usage |
| Dev server won't start | Clear cache, clean install |
See references/common-issues.md for detailed troubleshooting.
check_versions.sh - Show current vs available versionsclean_install.sh - Clean and reinstall dependenciestest_build.sh - Production build and serve testsrollback.sh - Revert to previous versionupgrade-guide.md - Full upgrade notes and package listcommon-issues.md - Compatibility issues and fixestesting-checklist.md - Comprehensive testing procedures