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

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:
11. Action Required:
13. Step 3: Markdown-it Async
14. Markdown-it now uses async rendering.
15. What Changed:
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:
24. Action Required:
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:
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:
40. Step 6: Code Block Changes
41. Markdown-it-attrs Disabled for Code Blocks
42. What Changed:
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:
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:
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:
61. Action Required:
63. Step 8: DocSearch v4 Upgrade
64. Algolia DocSearch upgraded to v4.
65. What Changed:
67. Action Required:
68. If you customized DocSearch styles:
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:
5. 2. Build Production Site
6. npm run docs:build
   

7. Check for:
9. 3. Preview Production Build
10. npm run docs:preview
    

11. Test:

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.