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:

• Explore new features in Overview
• Continue with Tutorial Basics
• Check out Tutorial Extras