Migration Guide

Guide for migrating from VitePress v1 to v2

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

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

Troubleshooting

Type errors with third-party Vite plugins

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.

Custom CSS not applying to code blocks

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

Search styles broken after upgrade

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

Build fails with 'markdown.render is not a function'

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

• Documentation: vitepress.dev
• GitHub Issues: vuejs/vitepress/issues
• Discord: chat.vuejs.org
• Changelog: CHANGELOG.md

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