Skip to main content

Config Migration Guide

About 5 minMigrationMigrationTheme Config

  // .vuepress/config.ts
- import theme from "vuepress-theme-hope";
+ import { defineUserConfig } from "vuepress";
+ import { hopeTheme } from "vuepress-theme-hope";

- export default theme.config({
+ export default defineUserConfig({
    // your site config here
    // ...

-   themeConfig:{
+   theme: hopeTheme({
      // your theme config here
      // ...
-   },
+   }),

Theme Usage

  • rename themeConfig to hopeTheme
  • rename navbarConfig to navbar
  • rename sidebarConfig to sidebar
  • added arraySidebar and objectSidebar helpers
  • remove config

Theme Options

  • changed author type from string | undefined to AuthorInfo[] | AuthorInfo | string[] | string | undefined

    interface AuthorInfo {
       * Author name
      name: string;
       * Author website
      url?: string;
       * Author email
      email?: string;

    This change allows you to add multiple authors and set sites for them.

  • unified nav, navbar to navbar

  • rename darkLogo to logoDark

  • rename navAutoHideto navbarAutoHide

  • added navbarIcon option to control navbar icon display

  • added navbarLayout option to control navbar layout

  • rename sidebarDepth to headerDepth

  • remove displayAllHeaders

  • support generating sidebar automatically from file structure

  • change items in navbar config to children

  • change title to text and path to link in sidebar configuration.

  • V2 navbar supports setting the Markdown file path directly like the sidebar to automatically generate text, icons and links

  • add activeMatch to control route activation

So both are unified as text, icon, prefix, link, children, activeMatch.

Since the theme no longer has a built-in search:

  • remove search, searchPlaceholder, searchMaxSuggestions

  • remove algolia, algoliaType

  • rename prevLinks to prevLink

  • rename nextLinks to nextLink

  • rename editLinks to editLink

  • rename updateTime to lastUpdated


  • Add iconAssets option

  • iconPrefix default value now infers from iconAssets

  • update values of darkmode option

    • add "enable"
    • rename "switch" to "toggle"
    • rename "auto-switch" to "switch"
  • themeColor and fullscreen is disabled by default

Blog Config

  • supports separate config in each language

  • add blog.description to set blogger description or motto

  • rename blog.links to blog.medias

  • change default value of blog.roundAvatar from true to false

  • rename blog.perPage to blog.articlePerPage

  • move blog.autoExcerpt to

Encryption Config

  • change encrypt.status: "global" | "local" (default "local") to boolean (default false)

  • rename to encrypt.admin

custom layout

  • remove custom

Page Layout

  • rename anchorDisplay to toc

Reading Speed

  • move wordPerMinute to plugins.readingTime.wordPerMinute

Plugin Changes


  • Added to control blog links
  • Added plugins.nprogress to control nprogress
  • Added plugins.prismjs to control Prism.js


Move all plugin related options under plugins.

  • rename activeHash to plugins.activeHeaderLinks

    The theme now uses official plugin @vuepress/plugin-active-header-links. warning

  • move comment moved to plugins.comment

    • Adds support for artalk, twikoo and giscus New

    • Vssue is currently missing warning

      Vssue is written in Vue2, and the author meteorlxyopen in new window has not yet made it compatible with Vue3 yet

    • Valine is removed removed

      Valine is lack of maintenance and can leak your privacy. You should use Walineopen in new window instead.

  • move copyCode to plugins.copyCode

  • move copyright to plugins.copyright

    The plugin is disabled by default now. warning

  • move feed to plugins.feed

    • Supports removing custom components and elements through plugins.feed.preservedElements options NEW

    • Visualized atom and rss feeds, configurable with plugins.feed.atomXslFilename plugins.feed.atomXslTemplate plugins.feed.rssXslFilename and plugins.feed.rssXslTemplate NEW

    • Customize feed generation via plugins.feed.getter option NEW

    • Multi-category support New

    • Move all output options from plugins.feed.output option to plugin option root and rename them.

      • feed.output.atom.enable renamed to plugins.feed.atom changed

      • feed.output.json.enable renamed to plugins.feed.json changed

      • feed.output.rss.enable renamed to plugins.feed.rss changed

      • feed.output.atom.path renamed to plugins.feed.atomOutputFilename changed

      • feed.output.json.path renamed to plugins.feed.jsonOutputFilename changed

      • feed.output.rss.path renamed to plugins.feed.rssOutputFilename

      • plugins.feed.atom, plugins.feed.json and plugins.feed.rss is false by default warning

        The theme no longer outputs feed files in three formats by default. If necessary, please set options to output formats needed.

  • move git to plugins.git

    The theme use official plugin @vuepress/plugin-git now. warning

  • move mdEnhance to plugins.mdEnhance

    • Markdown link check New

      The plugin now check your Markdown links and warn you when broken links are detected.

      You can control this behavior with plugins.mdEnhance.checkLinks option

    • image mark support New

      Use #light and #dark suffix to mark images to display them in light mode or dark mode via plugins.mdEnhance.imgMark option

    • Chart.js support New

      Adds chart.jsopen in new window support via plugins.mdEnhance.chart option

      ::: chart Title
        // chart.js config
      ::: chart Title
      const config = {
        // chart.js config
    • ECharts support New

      Adds EChartsopen in new window support via plugins.mdEnhance.echarts option

      ::: echarts Title
        // chart.js config
      ::: echarts Title
      const option = {
        // chart.js config
    • content include support New

      use @include to include other file content in Markdown via plugins.mdEnhance.include options.

      Use <!-- @include: filename --> to include a file.

      To partially import the file, you can specify the range of lines to be included:

      • <!-- @include: filename{start-end} -->
      • <!-- @include: filename{start-} -->
      • <!-- @include: filename{-end} -->

      Also, you can include file region:

      • <!-- @include: filename#region -->
    • tabs support New

      Use tabs container to create tabs via plugins.mdEnhance.tabs option.

    • add plugins.mdEnhance.gfm New

      Control supporting gfm

    • add plugins.mdEnhance.vPre New

      The following syntax is no longer built into VuePress2, so we add this option.

      ::: v-pre
    • rename mdEnhance.codegroup to plugins.mdEnhance.codetabs changed

    • rename plugins.mdEnhance.lazyLoad to plugins.mdEnhance.lazyLoad and change default value from true to false changed

    • remove plugins.mdEnhance.enableAll removed

      There are too many noob users who don't know what they are doing, and they just enable this option without using all the feature provided, yet they complain about load speed.

    • remove plugins.mdEnhance.lineNumbers removed

      VuePress2 supports line numbers config for code blocks individually

    • remove plugins.mdEnhance.imageFix removed

      Image related issues have been fixed in V2

  • move photoSwipe to plugins.photoSwipe

  • move pwa to plugins.pwa

    • plugins.pwa.update New: control the update logic of SW

      • "disabled": Do nothing even when new service worker is available. After new service work succeeds installing and starts waiting, it will control page and provide new content in next visit.

      • "available": Only display update popup when the new service worker is available

      • "hint": Display a hint to let user choose to refresh immediately

      • "force": unregister current service worker immediately then refresh to get new content

    • plugins.pwa.appendBase New: automatically insert base to the manifest option

    • plugins.pwa.hintComponent New: Hint component for detecting new content

    • shouldPrefetch hint New: Now the plugin will check shouldPrefetch option in config file and warn you to disable it.

    • plugins.pwa.cacheHTML default value changed from true to false changed

      This can effectively reduce the SW update time

    • pwa.popupComponent renamed to plugins.pwa.updateComponent changed

      This is because we added a new prompt popup window, so we need to avoid name confusion

  • move readingTime to plugins.readingTime

  • move seo to plugins.seo

    • JSON-LD support New

      The plugin now can generate JSON-LD script tags for you, and is providing an option plugin.seo.jsonLd to let you customize the JSON-LD properties.

    • Description generation New

      The plugin can generate a description for you automatically via plugin.seo.autoDescription options

    • Canonical link New

      You can set canonical link via plugin.seo.canonicalLink option. It's useful when your docs are deployed in several places.

    • seo.customMeta renamed to plugin.seo.customHead changed

      Now you can edit all head tags instead of only meta in V1.

  • move sitemap to plugins.sitemap

    • Visualized sitemap, configurable with plugins.sitemap.sitemapXSLFilename and plugins.sitemap.sitemapXSLTemplate New

    • plugin.sitemap.priority New: setting default value for priority

    • sitemap.urls renamed to plugin.sitemap.extraUrls changed

    • sitemap.exclude renamed to plugin.sitemap.excludeUrls changed

    • sitemap.outFile renamed to plugin.sitemap.sitemapFilename changed

    • sitemap.modifyTimeGetter renamed to plugin.sitemap.modifyTimeGetter changed


  • remove chunkRename

    The theme no longer provides this functionality.

  • remove cleanUrl

    The theme no longer provides this functionality.

  • remove git

    The theme now uses official plugin @vuepress/plugin-git.

  • remove smoothScroll

    The theme now provides smooth scrolling via CSS and no longer provides compatibility with older browsers.