::: warning Plugins and themes of VuePress v1 are not compatible with VuePress v2. You need to update them to corresponding v2 version. :::
Some major changes and enhancements of VuePress v2:
- VuePress v2 is now using Vue 3, so make sure your components and other client files are compatible with Vue 3.
- VuePress v2 is developed with TypeScript, so it provides better TS support now. It's highly recommended to use TypeScript to develop plugins and themes. VuePress config file also supports TypeScript, and you can use
.vuepress/config.ts
directly. - VuePress v2 supports both Webpack and Vite as bundler. Now Vite is the default bundler, while you can still choose to use Webpack. You can even use Vite in dev mode to get better development experience, and use Webpack in build mode to get better browser compatibility.
- VuePress v2 is now released as pure ESM packages, and CommonJS config files are no longer supported.
Core ideas and processes of VuePress v2 are the same with v1, while v2 API has been re-designed and becomes more normalized. So you might encounter breaking changes when migrating an existing v1 project to v2. This guide is here to help you migrating v1 sites / plugins / themes to v2.
- If you are a common user, you need to read the guide for users.
- If you are a plugin author, you need to read the guide for plugin authors.
- If you are a theme author, you need to read the guide for theme authors.
Config file should be in ESM format, and CommonJS format config file is no longer supported.
// .vuepress/config.js
- module.exports = {
- // user config
- }
+ export default {
+ // user config
+ }
Using a theme via string is not supported. Import the theme directly.
- module.exports = {
- theme: '@vuepress/theme-default',
- themeConfig: {
- // default theme config
- },
- }
+ import { defaultTheme } from 'vuepress'
+ export default {
+ theme: defaultTheme({
+ // default theme config
+ })
+ }
Removed. Set config to the theme directly.
Using a plugin via string is not supported. Import the plugin directly.
- module.exports = {
- plugins: [
- [
- '@vuepress/plugin-google-analytics',
- {
- id: 'G-XXXXXXXXXX',
- },
- ],
- ],
- }
+ import { googleAnalyticsPlugin } from '@vuepress/plugin-google-analytics'
+ export default {
+ plugins: [
+ googleAnalyticsPlugin({
+ id: 'G-XXXXXXXXXX',
+ }),
+ ],
+ }
Default value is changed from () => true
to true
.
Removed.
You can watch files manually in onWatched hook.
Renamed to pagePatterns
Moved to markdown.code.lineNumbers.
Default value is changed from false
to true
.
Removed.
Moved to markdown.links.externalAttrs.
Changed.
Removed.
Use markdown-it plugins in extendsMarkdown hook.
Removed.
Use extendsMarkdown hook.
Moved to markdown.headers.
All webpack related configs are moved to options of @vuepress/bundler-webpack
, including:
postcss
stylus
scss
sass
less
chainWebpack
configureWebpack
evergreen
: default value is changed fromfalse
totrue
- module.exports = {
- sass: { /* ... */ },
- }
+ import { webpackBundler } from '@vuepress/bundler-webpack'
+ export default {
+ bundler: webpackBundler({
+ sass: { /* ... */ },
+ }),
+ }
Please refer to Guide > Bundler.
Removed.
Use head instead. For example:
head:
- - meta
- name: foo
content: bar
- - link
- rel: canonical
href: foobar
- - script
- {}
- console.log('hello from frontmatter');
Has the same structure with:
// .vuepress/config.ts
export default {
// ...
head: [
['meta', { name: 'foo', content: 'bar' }],
['link', { rel: 'canonical', href: 'foobar' }],
['script', {}, `console.log('hello from frontmatter');`],
],
// ...
}
:i_month
: removed:i_day
: removed:minutes
: removed (undocumented in v1):seconds
: removed (undocumented in v1):regular
: renamed to:raw
See Frontmatter > permalinkPattern.
The stylus palette system of VuePress v1 (i.e. styles/palette.styl
and styles/index.styl
) is no longer provided by VuePress Core.
The palette system is extracted to @vuepress/plugin-palette.
Theme authors can use their own way to allow users to customize styles, and not be limited with stylus.
If you are using default theme, the palette system is still available but migrated to SASS, while most variables have been migrated to CSS variables. See Default Theme > Styles.
Renamed to .vuepress/client.{js,ts}
, and the usage has been changed, too.
See Advanced > Cookbook > Usage of Client Config.
Files in this directory will not be registered as Vue components automatically.
You need to use @vuepress/plugin-register-components, or register your components manually in .vuepress/client.{js,ts}
.
This directory will not be used as local theme implicitly if it is existed.
You need to import and set your local theme via theme option.
- Markdown slot is no longer supported.
- Markdown image syntax does not support webpack aliases anymore. Links without
./
prefix are also treated as relative links, which is aligned with the behavior of the native markdown image syntax. If you want to use aliases in image paths, or use images from external packages, you should use<img>
tag instead.
- ![](@alias/foo.png)
- ![](package-name/bar.png)
+ <img src="@alias/foo.png">
+ <img src="package-name/bar.png">
Removed.
-c, --cache [cache]
: changed to--cache <cache>
, which means that the shorthand-c
is not forcache
option, and the value ofcache
option is not optional.--no-cache
: renamed to--clean-cache
.
<CodeGroup />
and<CodeBlock />
renamed to<CodeGroup />
and<CodeGroupItem />
<Badge />
$badgeErrorColor
palette variable renamed to$badgeDangerColor
type
prop only acceptstip
,warning
anddanger
now
The palette system of default theme has migrated to SASS and CSS variables.
Default theme config has been changed a lot. You'd better check the config reference of v2 default theme to migrate it properly.
Here we list some notable changes:
- sidebar: {
- title: 'Foo Bar',
- path: '/foo/bar.html',
- collapsable: true,
- children: [
- ['/baz', 'Baz'],
- ],
- }
+ sidebar: {
+ text: 'Foo Bar',
+ link: '/foo/bar.html',
+ collapsible: true,
+ children: [
+ {
+ text: 'Baz',
+ link: '/baz',
+ }
+ ],
+ }
Check the v2 docs of official plugins.
Themes and plugins of v1 are not compatible with v2.
Please make sure that those themes and plugins you are using have supported v2, and refer to their own documentation for migration guide.
Some major breaking changes:
- You cannot use other plugins in your plugin anymore, which avoids lots of potential issues caused by plugin nesting. If your plugin depends on other plugins, you could list them in the docs to ask users import them manually. Alternatively, you can provide users with an array of plugins for convenience.
- Most of the v1 hooks have equivalents in v2. The only exception is
extendsCli
, which has been removed. - Webpack related hooks are removed, because VuePress Core has decoupled with webpack. You can try to use extendsBundlerOptions hook for similar purpose, and make sure to work with all bundlers.
For more detailed guide about how to write a plugin in v2, see Advanced > Writing a Plugin.
plugins
: removedready
: renamed toonPrepared
updated
: renamed toonWatched
generated
: renamed toonGenerated
additionalPages
: removed, useapp.pages.push(createPage())
inonInitialized
hookclientDynamicModules
: removed, useapp.writeTemp()
inonPrepared
hookenhanceAppFiles
: removed, useclientConfigFile
hookglobalUIComponents
: removed, useclientConfigFile
hookclientRootMixin
: removed, useclientConfigFile
hookextendMarkdown
: renamed toextendsMarkdown
chainMarkdown
: removedextendPageData
: renamed toextendsPage
extendsCli
: removedconfigureWebpack
: removedchainWebpack
: removedbeforeDevServer
: removedafterDevServer
: removed
See Plugin API.
Although we do not allow using other plugins in a plugin anymore, you can still use plugins in your theme.
Some major breaking changes:
- There is no conventional theme directory structure anymore.
- The file
theme/enhanceApp.js
will not be used as client app enhance file implicitly. You need to specify it explicitly inclientConfigFile
hook. - Files in
theme/global-components/
directory will not be registered as Vue components automatically. You need to use @vuepress/plugin-register-components, or register components manually inclientConfigFile
. - Files in
theme/layouts/
directory will not be registered as layout components automatically. You need to specify it explicitly inlayouts
option inclientConfigFile
. - Files in
theme/templates/
directory will not be used as dev / ssr template automatically. You need to specify theme explicitly intemplateBuild
andtemplateDev
option. - Always provide a valid js entry file, and do not use
"main": "layouts/Layout.vue"
as the theme entry anymore.
- The file
themeConfig
is removed from user config and site data. To access thethemeConfig
as you would viathis.$site.themeConfig
in v1, we now recommend using the @vuepress/plugin-theme-data plugin and itsuseThemeData
composition API.- Stylus is no longer the default CSS pre-processor, and the stylus palette system is not embedded. If you still want to use similar palette system as v1, @vuepress/plugin-palette may help.
- Markdown code blocks syntax highlighting by Prism.js is not embedded by default. You can use either @vuepress/plugin-prismjs or @vuepress/plugin-shiki, or implement syntax highlighting in your own way.
- For scalability concerns,
this.$site.pages
is not available any more.
For more detailed guide about how to write a theme in v2, see Advanced > Writing a Theme.
Removed.
Now you need to specify layout component in the client config file of your theme.
See Advanced > Writing a theme.
Renamed to extends
.
You can still inherit a parent theme with extends: parentTheme()
, which will extends the plugins, layouts, etc.
You can refer to Default Theme > Extending for how to extend default theme.
The @theme
and @parent-theme
aliases are removed by default, but you can still make a extendable theme with similar approach, see Advanced > Cookbook > Making a Theme Extendable.