I just upgraded my personal site from VuePress v1 to v2. Some things were very easy, some were not. Here are some of the things I learned from this project:

• The migration guide for VuePressopen in new window is an excellent resource.

• Since this migration also entails an upgrade for Vue, the Vue migration guide Breaking Changes sectionopen in new window will be useful too.

• Filters are no longer supported in Vue 3open in new window, but I had a bunch of those. ☹️

• The biggest fundamental change (IMO) is that $site.pages is no longer availableopen in new window “for scalability concerns.” I get that, but this makes writing components that show a list of pages difficult, but not impossible. The workaround is to use a temp fileopen in new window.

• Customizing the look and feel is super easy now that VuePress uses CSS variables.

• This fulltext-search pluginopen in new window is not compatible with v2, but you can make the page content (not just the headers) searchable by configuring the search plugin like so:

    [
        '@vuepress/plugin-search',
        { getExtraFields: (page) => [page.content] },
    ],
  

• VuePress v1 used to automatically register components in the .vuepress/components directory. To get that back you have to use the register-components pluginopen in new window.

• The @vuepress/blog plugin is not compatible with v2 (and I think it would have to be rewritten), but there are some nice features built in to VuePress that make me not miss that so much, such as extendsPageOptionsopen in new window.

Once VuePress v2 is out of beta there’s a number of documentation sites at work we’ll probably want to migrate. I wanted to know how big a job that will be, so I used this site as a test. There are still some rough edges, as evidenced by this bug I found while upgradingopen in new window (update: fixed in 2.0.0-beta.26open in new window). If you are interested, here’s the PR for this upgradeopen in new window.