Lewati ke konten utama
Versi: Next

Step-by-Step Migration Guide

✅ Systematic Approach

Follow these steps carefully to ensure a smooth migration from v1.0.0 to v1.1.0.

Prerequisites​

Before starting, ensure you have:

  • Node.js 20.0 or higher
  • pnpm 10.17.0 or higher
  • Git for version control
  • Backup of your current documentation

Step 1: Backup Your Project​

Create a backup before making any changes:

# Create a new branch for migration
git checkout -b migrate-to-v1.1.0

# Or create a backup copy
cp -r your-project your-project-backup

Step 2: Update Dependencies​

Update your package.json dependencies:

# Update Docusaurus to latest
pnpm update @docusaurus/core @docusaurus/preset-classic

# Check for outdated packages
pnpm outdated

Step 3: Update Sidebar Configuration​

For v1.1.0-dev (Current Version)​

File: sidebars.ts

Replace autogenerated sidebar with manual configuration:

import type {SidebarsConfig} from '@docusaurus/plugin-content-docs';

const sidebars: SidebarsConfig = {
  tutorialSidebar: [
    'intro',
    {
      type: 'category',
      label: '📚 Tutorial Basics',
      items: [
        'tutorial-basics/create-a-document',
        'tutorial-basics/create-a-page',
        'tutorial-basics/create-a-blog-post',
        'tutorial-basics/markdown-features',
        'tutorial-basics/using-tailwind',
        'tutorial-basics/deploy-your-site',
        'tutorial-basics/congratulations',
      ],
    },
    {
      type: 'category',
      label: '🔄 Migration Guide',
      items: [
        'migration/overview',
        'migration/breaking-changes',
        'migration/step-by-step',
      ],
    },
    {
      type: 'category',
      label: '🔧 Tutorial Extras',
      items: [
        'tutorial-extras/manage-docs-versions',
        'tutorial-extras/translate-your-site',
      ],
    },
  ],
};

export default sidebars;

For v1.0.0 (Stable Version)​

File: versioned_sidebars/version-1.0.0-sidebars.json

Update to manual structure (without Migration Guide):

{
  "tutorialSidebar": [
    {
      "type": "doc",
      "id": "intro",
      "label": "Introduction"
    },
    {
      "type": "category",
      "label": "Tutorial Basics",
      "items": [
        "tutorial-basics/create-a-document",
        "tutorial-basics/create-a-page",
        "tutorial-basics/using-tailwind"
      ]
    },
    {
      "type": "category",
      "label": "Tutorial Extras",
      "items": [
        "tutorial-extras/manage-docs-versions",
        "tutorial-extras/translate-your-site"
      ]
    }
  ]
}

Step 4: Create Migration Documentation​

Create the migration guide folder structure:

# Create migration folder
mkdir docs/migration

# Create category metadata
touch docs/migration/_category_.json

File: docs/migration/_category_.json

{
  "label": "🔄 Migration Guide",
  "position": 2,
  "link": {
    "type": "generated-index",
    "description": "Learn how to migrate from v1.0.0 to v1.1.0"
  }
}

Create migration documentation files:

  • docs/migration/overview.md
  • docs/migration/breaking-changes.md
  • docs/migration/step-by-step.md

Step 5: Update Docusaurus Configuration​

File: docusaurus.config.ts

Ensure versioning configuration is set correctly:

docs: {
  sidebarPath: './sidebars.ts',
  lastVersion: '1.0.0',
  versions: {
    current: {
      label: '🚀 Next (1.1.0-dev)',
      path: 'next',
      banner: 'unreleased',
    },
    '1.0.0': {
      label: '✅ Latest (1.0.0)',
      path: '/',
      banner: 'none',
    },
  },
},

Step 6: Test Locally​

Build and serve your documentation:

# Clear cache
pnpm run clear

# Build production
pnpm run build

# Serve locally
pnpm run serve

Test the following:

  • v1.0.0 sidebar shows correctly (NO Migration Guide)
  • v1.1.0-dev sidebar shows Migration Guide category
  • Version switcher works in navbar
  • All links work correctly
  • Dark mode works properly
  • i18n language switcher works

Step 7: Verify Version-Specific Content​

Check v1.0.0 (Stable)​

Visit: http://localhost:3000/docs/intro

Verify:

  • ✅ Green badge shows "v1.0.0 Stable"
  • ✅ Sidebar has 2 categories (Basics, Extras)
  • ❌ NO Migration Guide in sidebar

Check v1.1.0-dev (Next)​

Visit: http://localhost:3000/docs/next/intro

Verify:

  • ✅ Yellow/Orange badge shows "v1.1.0-dev"
  • ✅ Sidebar has 3 categories (Basics, Migration Guide, Extras)
  • ✅ Migration Guide accessible and readable

Step 8: Update i18n Translations​

If using Indonesian translation:

# Generate translation files
pnpm run write-translations -- --locale id

# Update sidebar labels

File: i18n/id/docusaurus-plugin-content-docs/current.json

Add translations for new sidebar items:

{
  "sidebar.tutorialSidebar.category.🔄 Migration Guide": {
    "message": "🔄 Panduan Migrasi",
    "description": "The label for category Migration Guide in sidebar tutorialSidebar"
  }
}

Step 9: Deploy to Production​

When ready to deploy:

# Commit changes
git add .
git commit -m "Migrate to v1.1.0: Add migration guide and update sidebars"

# Create version tag
git tag v1.1.0

# Push to repository
git push origin migrate-to-v1.1.0
git push --tags

Common Issues and Solutions​

Issue 1: Sidebar Not Showing​

Problem: Sidebar appears empty or shows error

Solution:

# Clear Docusaurus cache
pnpm run clear

# Rebuild
pnpm run build

Issue 2: Migration Guide Not Found​

Problem: 404 error when accessing migration guide

Solution: Ensure files exist in docs/migration/ folder:

  • _category_.json
  • overview.md
  • breaking-changes.md
  • step-by-step.md

Issue 3: Version Switcher Not Working​

Problem: Can't switch between versions

Solution: Check docusaurus.config.ts:

// Ensure this is in navbar items
{
  type: 'docsVersionDropdown',
  position: 'right',
}

Rollback Instructions​

If you need to rollback:

# Checkout previous version
git checkout v1.0.0

# Or restore from branch
git checkout main
git branch -D migrate-to-v1.1.0

Post-Migration Checklist​

After migration, verify:

  • All documentation pages load correctly
  • Search functionality works
  • Links between pages work
  • Images and assets display properly
  • Dark mode works in all pages
  • i18n language switcher works
  • Version switcher works
  • Mobile responsive design intact
  • Build succeeds without errors
  • No broken links

Need Help?​

If you encounter issues:

  1. Review Breaking Changes
  2. Check Migration Overview
  3. Search GitHub issues
  4. Create new issue with detailed error log

Congratulations! 🎉​

You've successfully migrated to v1.1.0!

Your documentation now has:

  • ✅ Enhanced versioning with clear separation
  • ✅ Multi-language support (i18n)
  • ✅ Better navigation with manual sidebars
  • ✅ Migration guide for future upgrades

Next Steps: