Config Migration Guide

TS

  // .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
      // ...
-   },
+   }),
  });

JS

// .vuepress/config.js
- const { config } = require("vuepress-theme-hope");
+ import { hopeTheme } from "vuepress-theme-hope";

- module.exports = theme.config({
+ export default {
    // 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.

Navigation Bar

• 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

Sidebar

• rename sidebarDepth to headerDepth

• remove displayAllHeaders

• support generating sidebar automatically from file structure

Navbar Sidebar Config Unified

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

Search

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

• remove search, searchPlaceholder, searchMaxSuggestions

• remove algolia, algoliaType

Page Link

• rename prevLinks to prevLink

• rename nextLinks to nextLink

• rename editLinks to editLink

• rename updateTime to lastUpdated

Outlook

• 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 plugins.blog.excerptLength

Encryption Config

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

• rename encrypt.global to encrypt.admin

custom layout

• remove custom

Page Layout

• rename anchorDisplay to toc

Reading Speed

• move wordPerMinute to plugins.readingTime.wordPerMinute

Plugin Changes

Addition

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

Changes

Move all plugin related options under plugins.

• rename activeHash to plugins.activeHeaderLinks

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

• move comment moved to plugins.comment

  • Adds support for artalk, twikoo and giscus

  • Vssue is currently missing

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

  • Valine is removed

    Valine is lack of maintenance and can leak your privacy. You should use Waline instead.

• move copyCode to plugins.copyCode

• move copyright to plugins.copyright

  The plugin is disabled by default now.

• move feed to plugins.feed

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

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

  • Customize feed generation via plugins.feed.getter option

  • Multi-category support

  • 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

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

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

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

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

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

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

      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.

• move mdEnhance to plugins.mdEnhance

  • Markdown link check

    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

    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

    Adds chart.js support via plugins.mdEnhance.chart option

    ::: chart Title
    
    ```json
    {
      // chart.js config
    }
    ```
    
    :::
    
    ::: chart Title
    
    ```js
    const config = {
      // chart.js config
    };
    ```
    
    :::
    

  • ECharts support

    Adds ECharts support via plugins.mdEnhance.echarts option

    ::: echarts Title
    
    ```json
    {
      // chart.js config
    }
    ```
    
    :::
    
    ::: echarts Title
    
    ```js
    const option = {
      // chart.js config
    };
    ```
    
    :::
    

  • content include support

    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

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

  • add plugins.mdEnhance.gfm

    Control supporting gfm

  • add plugins.mdEnhance.vPre

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

    ::: v-pre
    
    :::
    

  • rename mdEnhance.codegroup to plugins.mdEnhance.codetabs

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

  • remove plugins.mdEnhance.enableAll

    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

    VuePress2 supports line numbers config for code blocks individually

  • remove plugins.mdEnhance.imageFix

    Image related issues have been fixed in V2

• move photoSwipe to plugins.photoSwipe

• move pwa to plugins.pwa

  • plugins.pwa.update : 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 : automatically insert base to the manifest option

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

  • shouldPrefetch hint : 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

    This can effectively reduce the SW update time

  • pwa.popupComponent renamed to plugins.pwa.updateComponent

    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

    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

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

  • Canonical link

    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

    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

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

  • sitemap.urls renamed to plugin.sitemap.extraUrls

  • sitemap.exclude renamed to plugin.sitemap.excludeUrls

  • sitemap.outFile renamed to plugin.sitemap.sitemapFilename

  • sitemap.modifyTimeGetter renamed to plugin.sitemap.modifyTimeGetter

Deletion

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