Config Migration Guide

About 5 min

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 {
      name: string;
      url?: 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

  • 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, and change default value from true to false

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 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 service 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.customElements options NEW

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

    • Multi-category support New

    • Move all output options from plugins.feed.ouput 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.linkCheck 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.imageMark option

    • Chart.js support New

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

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

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

      ::: echarts Title
        // chart.js config
      ::: echarts Title
      module.exports = {
        // 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})
    • 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

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

    • 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 descrption 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

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

      Now you can edit all head tags intead of only meta in V1. are deployed in several places.

  • move sitemap to plugins.sitemap

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