Skip to main content

​
Migration Guide

This guide will help you migrate your VitePress site from v1.x to v2.x (currently in alpha).

​
Overview

VitePress v2.0 brings significant improvements including Vite 7 support, Shiki v3 integration, and performance enhancements. While most changes are backwards compatible, there are several breaking changes to be aware of.
VitePress v2.0 is currently in alpha (v2.0.0-alpha.16). Test thoroughly before deploying to production.

​
Breaking Changes

1
Step 1: Update Dependencies
2
Update VitePress to v2.x in your package.json:
3
{
  "devDependencies": {
    "vitepress": "^2.0.0-alpha.16"
  }
}
4
Run your package manager to install:
5
npm install
# or
pnpm install
# or
yarn install
6
Step 2: Vite 7 Upgrade
7
VitePress v2 uses Vite 7. For most users, no change is required.
8
If you use third-party Vite plugins, you may encounter type mismatches. See the Vite migration guide for details.
9
What Changed:
10
  • Vite upgraded from v5 to v7
  • Better performance and smaller bundle sizes
  • Potential plugin compatibility issues
    • 11
    Action Required:
    12
  • Review your custom Vite plugins
  • Suppress type errors with @ts-expect-error or as any if needed
  • Report issues to respective plugin repositories
    • 13
    Step 3: Markdown-it Async
    14
    Markdown-it now uses async rendering.
    15
    What Changed:
    16
  • markdown-it-async is used instead of markdown-it
  • Affects custom content renderers for local search
    • 17
    Action Required:
    18
    If you have custom content renderer:
    19
    // ❌ Before (v1.x)
const html = md.render(content)

// ✅ After (v2.x)
const html = await md.renderAsync(content)
    20
    Step 4: Shiki v3 Migration
    21
    VitePress v2 uses Shiki v3 for syntax highlighting.
    22
    What Changed:
    23
  • Upgraded from Shiki v2 to v3
  • New matching algorithm for transformers
  • Improved language lazy loading
  • Better performance
    • 24
    Action Required:
    25
  • Review custom Shiki transformers
  • Update transformer configurations if needed
  • Test syntax highlighting in your code blocks
    • 26
    Step 5: Configuration Updates
    27
    CJK Emphasis Config Rename
    28
    What Changed:
    29
    // ❌ Before (v2.0.0-alpha.12 and earlier)
export default {
  markdown: {
    cjkFriendly: false
  }
}

// ✅ After (v2.0.0-alpha.13+)
export default {
  markdown: {
    cjkFriendlyEmphasis: false
  }
}
    30
    Who’s Affected: Only users who explicitly disabled CJK-friendly emphasis need to update.
    31
    PostCSS Isolate Styles
    32
    What Changed:
    33
  • includeFiles now defaults to [/vp-doc\.css/, /base\.css/]
  • transform and exclude options removed
    • 34
    Action Required:
    35
    // If you were using:
export default {
  vite: {
    css: {
      postcss: {
        plugins: [
          postcssIsolateStyles({
            includeFiles: [/vp-doc\.css/]
          })
        ]
      }
    }
  }
}

// You can now remove explicit includeFiles:
export default {
  vite: {
    css: {
      postcss: {
        plugins: [postcssIsolateStyles()]
      }
    }
  }
}
    36
    Glob Options Restriction
    37
    What Changed: Only cwd, ignore, dot, and debug are supported in globOptions of createContentLoader.
    38
    Action Required:
    39
  • Remove unsupported glob options
  • Suppress type errors if needed for advanced use cases
    • 40
    Step 6: Code Block Changes
    41
    Markdown-it-attrs Disabled for Code Blocks
    42
    What Changed:
    43
  • markdown-it-attrs is disabled for fenced code blocks
  • Use Shiki transformers for adding classes instead
    • 44
    Action Required:
    45
    // ❌ Before - Using markdown-it-attrs
// ```js {.my-class}
// code here
// ```

// ✅ After - Use Shiki transformers
export default {
  markdown: {
    codeTransformers: [
      // Add your custom transformer
    ]
  }
}
    46
    CSS Class Changes
    47
    What Changed:
    48
  • vp-code class removed from code blocks
  • vp-adaptive-theme class no longer added for single theme
    • 49
    Action Required:
    50
    Update your custom CSS:
    51
    /* ❌ Before */
.vp-code {
  /* styles */
}

/* ✅ After - Use .shiki instead */
.shiki {
  /* styles */
}

/* Or be more specific */
pre.shiki {
  /* styles */
}

[class*='language-'] pre {
  /* styles */
}
    52
    Step 7: Theme Component Changes
    53
    Layout Composables
    54
    What Changed:
    55
  • useLocalNav and useSidebar removed
  • Use useLayout instead
    • 56
    Action Required:
    57
    // ❌ Before
import { useLocalNav, useSidebar } from 'vitepress/theme'

const localNav = useLocalNav()
const sidebar = useSidebar()

// ✅ After
import { useLayout } from 'vitepress/theme'

const layout = useLayout()
    58
    Type Removals
    59
    What Changed:
    60
  • DefaultTheme.DocSidebar type removed
  • DefaultTheme.DocLocalNav type removed
    • 61
    Action Required:
    62
  • Update TypeScript imports if you were using these types
    • 63
    Step 8: DocSearch v4 Upgrade
    64
    Algolia DocSearch upgraded to v4.
    65
    What Changed:
    66
  • DocSearch v4 with sidepanel support
  • AI features available in private beta
    • 67
    Action Required:
    68
    If you customized DocSearch styles:
    69
  • Review navbar search button styles
  • Review modal styles
  • Test search functionality
    • 70
    Apply for AI features: https://forms.gle/iyfb5pC2CiiwszUKA

    ​
    New Features

    Take advantage of these new features in v2:

    Vite 7 Performance

    Faster build times and improved development experience with Vite 7.

    Shiki v3 Highlighting

    Better syntax highlighting with lazy-loaded languages and improved performance.

    Async Markdown Rendering

    More powerful markdown processing with async support.

    Enhanced DocSearch

    DocSearch v4 with sidepanel and AI-powered search (beta).

    ​
    CJK-Friendly Emphasis

    Enabled by default for better CJK language support: 
    // Automatically enabled - intentionally deviates from CommonMark spec
// for better CJK user experience

// To disable:
export default {
  markdown: {
    cjkFriendlyEmphasis: false
  }
}

    ​
    Distributed Config Files

    Support for multiple config files across your project: 
    // .vitepress/config.ts (root)
// packages/docs/.vitepress/config.ts (package-specific)

    ​
    Custom Display Names for Code Blocks

    ```js [filename.js]
console.log('Hello World')

    
### Router Enhancements

```typescript
import { useRouter } from 'vitepress'

const router = useRouter()

// History replacement
router.go('/path', { replace: true })

// Same-page navigation
router.go('#section')

// Decoded hash and query
console.log(router.route.hash)
console.log(router.route.query)

    ​
    Testing Your Migration

    1
    1. Run Development Server
    2
    npm run docs:dev
    3
    Verify:
    4
  • Site loads without errors
  • Navigation works correctly
  • Code blocks render properly
  • Search functions as expected
    • 5
    2. Build Production Site
    6
    npm run docs:build
    7
    Check for:
    8
  • Build completes successfully
  • No breaking errors in console
  • CSS is correctly loaded
  • All pages render
    • 9
    3. Preview Production Build
    10
    npm run docs:preview
    11
    Test:
    12
  • All routes work
  • Client-side navigation
  • Code syntax highlighting
  • Theme switching
  • Search functionality

    • ​
    Troubleshooting

    Vite 7 may cause type mismatches with some plugins. Solutions:
    import somePlugin from 'some-vite-plugin'

export default {
  vite: {
    // @ts-expect-error - Plugin types not updated for Vite 7
    plugins: [somePlugin()]
  }
}
    Or suppress with as any and report to plugin repository.
    If your code block styles aren’t working:
    1. Replace .vp-code with .shiki
    2. Check for vp-adaptive-theme class usage
    3. Use pre.shiki or [class*='language-'] pre selectors
    DocSearch v4 changed class names and structure:
    1. Review custom DocSearch CSS
    2. Update selectors for navbar search button
    3. Update modal styles
    4. Test on mobile viewports
    This happens with custom content renderers:
    // Update to async
const html = await md.renderAsync(content)

    ​
    Rollback Instructions

    If you need to rollback to v1.x: 
    {
  "devDependencies": {
    "vitepress": "^1.6.3"
  }
}
    Then run: 
    npm install
# or
pnpm install

    ​
    Getting Help

    For the latest breaking changes and migration notes, always check the official changelog.

    Build docs developers (and LLMs) love

    Get started for freeTalk to us