配置迁移指南

大约 7 分钟

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

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

主题使用

移除 config
themeConfig 重命名为 hopeTheme
navbarConfig 重命名为 navbar
sidebarConfig 重命名为 sidebar
新增 arraySidebar, objectSidebar

主题配置

interface AuthorInfo {
  /**
   * 作者姓名
   */
  name: string;

  /**
   * 作者网站
   */
  url?: string;

  /**
   * 作者 Email
   */
  email?: string;
}

此改动允许你添加多个作者，并为其设置网站。

导航栏

nav, navbar 统一为 navbar
darkLogo 重命名为 logoDark
navAutoHide 重命名为 navbarAutoHide
新增 navbarIcon 选项控制导航栏图标
新增 navbarLayout 选项控制导航栏布局

由于主题不再内置搜索:

移除 search, searchPlaceholder, searchMaxSuggestions
移除 algolia, algoliaType

侧边栏

sidebarDepth 重命名为 headerDepth
移除 displayAllHeaders
支持从文件结构中生成侧边栏

导航栏侧边栏配置统一

导航栏配置中的 items 改为 children
侧边栏配置中的 title 改为 text, path 改为 link。
V2 导航栏支持像侧边栏一样直接设置 Markdown 文件路径自动生成文字、图标与链接

这样他们的配置统一为 text, icon, prefix, link, children。

两者配置新增 activeMatch 控制激活情况

页面链接

prevLinks 重命名为 prevLink
nextLinks 重命名为 nextLink
editLinks 重命名为 editLink
updateTime 重命名为 lastUpdated

外观

新增 iconAssets 选项
iconPrefix 默认值从 iconAssets 推断
更新 darkmode 选项的值
- 添加 "enable"
- 将 "switch" 重命名为 "toggle"
- 将 "auto-switch" 重命名为 "switch"
默认禁用 themeColor 与 fullscreen

博客配置

博客配置现在支持在每个语言中单独配置
新增 blog.description 配置博主描述或座右铭
blog.links 重命名为 blog.medias
blog.roundAvatar 默认值由 true 改为 false
blog.perPage 重命名为 blog.articlePerPage
blog.autoExcerpt 移动至 plugins.blog.excerptLength

加密配置

encrypt.status: "global" | "local" (默认 "local") 改为 encrypt.global: boolean (默认 false)
encrypt.global 重命名为 encrypt.admin

自定义布局

移除 custom

页面布局

anchorDisplay 重命名为 toc

阅读速度

wordPerMinute 移至 plugins.readingTime.wordPerMinute

插件变更

新增

新增 plugins.blog 控制博客地址
新增 plugins.nprogress 控制加载进度条
新增 plugins.prismjs 控制是否启用 Prism.js 高亮代码块

改动

所有插件相关选项均被移至 plugins 下。

activeHash 移动至 plugins.activeHeaderLinks
主题现在使用 @vuepress/plugin-active-header-links 官方插件。
comment 移动至 plugins.comment
- 添加 artalk、twikoo 和 giscus 评论服务的支持
- Vssue 目前缺失
  Vssue 是用 Vue2 编写的，作者 meteorlxyopen in new window 尚未使其与 Vue3 兼容
- Valine 服务被移除
  Valine 缺乏维护，并且它可能会泄露你的隐私。你应该改用 Walineopen in new window。
copyCode 移动至 plugins.copyCode
copyright 移动至 plugins.copyright
插件默认禁用
feed 移动至 plugins.feed
- 支持通过 plugins.feed.preservedElements 选项保留自定义组件和元素
- 可视化的 Atom 和 RSS 流，支持通过 plugins.feed.atomXslFilename plugins.feed.atomXslTemplate plugins.feed.rssXslFilename 和 plugins.feed.rssXslTemplate 配置
- 通过 plugins.feed.getter 选项完全自定义 Feed 生成
- 多分类支持
- 所有的输出选项从插件选项中的 output 选项移出到根选项下，并进行了重命名。
  - feed.output.atom.enable 重命名为 plugins.feed.atom
  - feed.output.json.enable 重命名为 plugins.feed.json
  - feed.output.rss.enable 重命名为 plugins.feed.rss
  - feed.output.atom.path 重命名为 plugins.feed.atomOutputFilename
  - feed.output.json.path 重命名为 plugins.feed.jsonOutputFilename
  - feed.output.rss.path 重命名为 plugins.feed.rssOutputFilename
- plugins.feed.atom, plugins.feed.json 和 plugins.feed.rss 现在默认为 false
  主题不再默认输出三种格式的 Feed 文件，你需要手动启用以输出需要的格式。
git 移动至 plugins.git
主题现在使用官方插件 @vuepress/plugin-git，所以支持选项有变化。
mdEnhance 移动至 plugins.mdEnhance
- Markdown 链接检查
  该插件现在检查你的 Markdown 链接，并在检测到损坏的链接时警告你。
  你可以通过 plugins.mdEnhance.checkLinks 选项控制此行为
- 图像标记支持
  通过 plugins.mdEnhance.imgMark 使用 #light 和 #dark 后缀标记图像以在日间模式或夜间模式下显示它们。
- Chart.js 支持
  新增 plugins.mdEnhance.chart 选项提供 chart.jsopen in new window 支持
```
::: chart 标题

```json
  {
    // chart.js 配置
  }
```

:::

::: chart 标题

```js
  const config = {
    // chart.js 配置
  };
```

:::
```
- ECharts 支持
  新增 plugins.mdEnhance.echarts 选项提供 EChartsopen in new window 支持。
```
::: echarts 标题

```json
  {
    // echarts 配置
  }
```

:::

::: echarts 标题

```js
  const option = {
    // echarts 配置
  };
```

:::
```
- 包含文件支持
  新增 plugins.mdEnhance.include 选项使用 @include 将其他文件内容导入到 Markdown 中。
  使用  导入文件。
  如果要部分导入文件，你可以指定导入的行数
  - 
  - 
  - 
  同时你也可以导入文件区域:
  - 
- 选项卡支持
  新增 plugins.mdEnhance.tabs 选项通过 tabs 容器创建选项卡。
- plugins.mdEnhance.gfm
  一键支持 GFM
- plugins.mdEnhance.vPre
  VuePress 2 从 @vuepress/core 中删除了以下容器支持，因此添加了此选项
```
::: v-pre

一些 {{vue 语法}}。

:::
```
- mdEnhance.codegroup 重命名为 plugins.mdEnhance.codetabs
- plugins.mdEnhance.lazyLoad 改为 plugins.mdEnhance.imgLazyload，默认值由 true 改为 false
- 移除 plugins.mdEnhance.enableAll
  有太多不知道自己在做什么的菜鸟用户，他们只是启用此选项而没有使用提供的所有功能，但他们抱怨加载速度。
- 移除 plugins.mdEnhance.lineNumbers
  VuePress2 支持单独对代码块配置行号
- 移除 plugins.mdEnhance.imageFix
  图片相关问题已在 V2 中得到修正
photoSwipe 移动至 plugins.photoSwipe
pwa 移动至 plugins.pwa
- plugins.pwa.update : 控制 SW 的更新逻辑
  - "disabled": 即使有新的 service worker 也不做任何事情，新的 service work 开始等待后，会在用户下次访问时接管页面，让用户获得新内容。
  - "available": 仅当新的 service worker 可用时才显示更新弹出窗口
  - "hint": 显示更新内容可用提示，并允许用户立即刷新。当新的 SW 成功注册后，将转为更新内容就绪弹窗。
    当你希望用户立即查看新文档时，这很有帮助。
  - "force": 立即注销当前 Service Worker 然后刷新以获取新内容
- plugins.pwa.appendBase : 自动向 manifest 选项插入 base
- plugins.pwa.hintComponent : 检测到新内容的提示组件
- shouldPrefetch 提示 : 现在插件将检查配置文件中的 shouldPrefetch 选项并警告你禁用它。
- plugins.pwa.cacheHTML 默认值由 true 改为 false
  这能有效降低 SW 更新时间
- pwa.popupComponent 重命名为 plugins.pwa.updateComponent
  这是因为我们新增了一个提示弹窗，所以需要避免名称混淆
readingTime 移动至 plugins.readingTime
seo 移动至 plugins.seo
- JSON-LD 支持
  该插件现在可以为你生成 JSON-LD 脚本标签，并提供一个选项 plugins.seo.jsonLd 让你自定义 JSON-LD 属性。
- 自动描述生成
  该插件可以通过 plugins.seo.autoDescription 选项自动为你生成描述
- 规范链接
  你可以通过 plugins.seo.canonicalLink 选项设置规范链接。当你的文档部署在多个地方时，它很有用。
- seo.customMeta 重命名为 plugins.seo.customHead
  现在你可以编辑所有 <head> 标签，而不是仅 <meta> 标签。
sitemap 移动至 plugins.sitemap
- 可视化的站点地图，支持通过 plugins.sitemap.sitemapXSLFilename 和 plugins.sitemap.sitemapXSLTemplate 配置
- plugins.sitemap.priority : 设置优先级的默认值
- sitemap.urls 重命名为 plugins.sitemap.extraUrls
- sitemap.exclude 重命名为 plugins.sitemap.excludeUrls
- sitemap.outFile 重命名为 plugins.sitemap.sitemapFilename
- sitemap.modifyTimeGetter 重命名为 plugins.sitemap.modifyTimeGetter

移除

移除 chunkRename
主题不再提供此功能。
移除 cleanUrl
主题不再提供此功能。
移除 smoothScroll
主题现在通过 CSS 提供平滑滚动，不再对旧浏览器提供兼容。

配置迁移指南

# 主题使用

# 主题配置

# 导航栏

# 侧边栏

# 导航栏侧边栏配置统一

# 页面链接

# 外观

# 博客配置

# 加密配置

# 自定义布局

# 页面布局

# 阅读速度

# 插件变更

# 新增

# 改动

# 移除

主题使用

主题配置

导航栏

侧边栏

导航栏侧边栏配置统一

页面链接

外观

博客配置

加密配置

自定义布局

页面布局

阅读速度

插件变更

新增

改动

移除