Aug 30, 2021

VuePress v2

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 VuePress is an excellent resource.

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

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

• The biggest fundamental change (IMO) is that $site.pages is no longer available “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 file.

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

• This fulltext-search plugin 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 plugin.

• 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 extendsPageOptions.

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 upgrading (update: fixed in 2.0.0-beta.26). If you are interested, here’s the PR for this upgrade.