Skip to main content
Version: Migration Guide (1.2.0)

Breaking Changes

⚠️ Important Changes

Review these breaking changes carefully before upgrading to v1.1.0.

Overview​

Version 1.1.0 introduces some breaking changes that may require updates to your existing documentation setup.

1. Sidebar Configuration Changes​

What Changed​

The sidebar configuration moved from autogenerated to manual structure.

v1.0.0 (Old):

const sidebars: SidebarsConfig = {
  tutorialSidebar: [{type: 'autogenerated', dirName: '.'}],
};

v1.1.0 (New):

const sidebars: SidebarsConfig = {
  tutorialSidebar: [
    'intro',
    {
      type: 'category',
      label: '📚 Tutorial Basics',
      items: [...],
    },
  ],
};

Impact​

  • ⚠️ High if you customized sidebar order
  • ⚠️ Medium if you relied on auto-generated order
  • ✅ Low if using default structure

Action Required​

Update sidebars.ts to explicitly define sidebar items. See Step-by-Step Guide.

2. Version-Specific Content​

What Changed​

Each version now has independent sidebar and content structure.

Before:

  • Single sidebar for all versions
  • Content changes affected all versions

After:

  • v1.0.0: versioned_sidebars/version-1.0.0-sidebars.json
  • v1.1.0-dev: sidebars.ts

Impact​

  • ⚠️ High if maintaining multiple versions
  • ✅ Low if only using single version

Action Required​

Review versioned_sidebars/ folder and ensure each version has correct sidebar configuration.

3. i18n Configuration​

What Changed​

Added internationalization support with Indonesian language.

New Config:

i18n: {
  defaultLocale: 'en',
  locales: ['en', 'id'],
  localeConfigs: {
    en: { label: 'English', ... },
    id: { label: 'Bahasa Indonesia', ... },
  },
}

Impact​

  • ✅ None if not using i18n
  • ⚠️ Low if using different locales

Action Required​

None, unless you want to add more languages.

4. Blog Functionality Removed​

What Changed​

Blog feature was disabled in configuration.

Change:

blog: false, // Previously blog: { ... }

Impact​

  • ⚠️ High if using blog feature
  • ✅ None if not using blog

Action Required​

If you need blog feature, set blog back to an object with blog configuration.

5. Semantic Utility Classes​

What Changed​

Enhanced semantic utilities with d- prefix for better dark mode support.

New Classes:

  • d-bg-primary → Auto dark mode background
  • d-text-primary → Auto dark mode text
  • d-border-primary → Auto dark mode border

Impact​

  • ✅ None for existing content
  • ⚠️ Low if creating new styled components

Action Required​

Optional: Update custom components to use new semantic utilities for better dark mode.

Compatibility Matrix​

Featurev1.0.0v1.1.0Compatible?
Autogenerated Sidebar✅ Yes❌ No⚠️ Needs update
Manual Sidebar✅ Yes✅ Yes✅ Compatible
i18n Support❌ No✅ Yes✅ Backward compatible
Blog Feature✅ Yes❌ No⚠️ Config change needed
Versioning✅ Yes✅ Enhanced✅ Compatible
Dark Mode✅ Yes✅ Enhanced✅ Compatible

Migration Risk Assessment​

Low Risk ✅​

  • i18n configuration (opt-in)
  • Semantic utility classes (additive)
  • Version management (improved)

Medium Risk ⚠️​

  • Sidebar configuration (requires manual update)
  • Version-specific content (new structure)

High Risk 🔴​

  • Blog feature removal (if used)

Rollback Plan​

If you encounter issues after migration:

  1. Restore from backup

    git checkout v1.0.0

  2. Keep v1.0.0 running while fixing v1.1.0

  3. Use version selector to let users choose stable version

danger

Always test migration in a non-production environment first!

Next Steps​

Ready to migrate? Follow the Step-by-Step Guide →