建议各位还是去看官方文档，本文只是我使用过程中随手写的笔记

简介

VuePress中文文档(v2.x)：https://v2.vuepress.vuejs.org/zh/
或者VuePress GitHub Pages(最新)：https://vuepress.github.io/
Github仓库：https://github.com/vuepress/vuepress-next

VuePress 是一个以 Markdown 为中心的静态网站生成器。你可以使用 Markdown 来书写内容（如文档、博客等），然后 VuePress 会帮助你生成一个静态网站来展示它们。

VuePress 诞生的初衷是为了支持 Vue.js 及其子项目的文档需求，但是现在它已经在帮助大量用户构建他们的文档、博客和其他静态网站。

快速上手

依赖环境

  1. Node.js v14.18.0+ （查看版本node -v，内置npm）
  2. Yarn v1 classic （可选，全局安装命令npm install yarn -g，查看版本yarn -v）

百里飞洋：安装完Yarn后，为了提升下载依赖的速度，建议全局设置为国内镜像源

1
2
3
4
5
6
7
8
# 查看当前源，默认是https://registry.yarnpkg.com
yarn config get registry

# 全局设置源地址为：淘宝源或内网源
yarn config set registry https://registry.npm.taobao.org --global

# 如果想恢复官方源
yarn config set registry https://registry.yarnpkg.com --global

手动安装

下方代码帮助你手动从头搭建一个简单的 VuePress 文档网站。

如果你想在一个现有项目中使用 VuePress 管理文档，从步骤 3 安装依赖开始。

  • 步骤1: 创建并进入一个新目录

    1
    2
    mkdir vuepress-starter # 创建空文件夹，名称自定义
    cd vuepress-starter # 进入该文件夹

  • 步骤2: 初始化项目

    1
    2
    git init # 生成.git文件夹
    yarn init # 一路回车即可，生成package.json文件

    百里飞洋：这里不要使用git bash窗口操作命令，使用cmd或者powerShell。否则yarn init命令报错Can't answer a question unless a user TTY

  • 步骤3: 将 VuePress 安装为本地依赖，根目录会生成依赖文件夹node_modules和依赖版本锁定文件yarn.lock

    1
    yarn add -D vuepress@next

  • 步骤4: 在 package.json 中添加一些 scripts，它们是实现与包相关的任务自动化的脚本

    1
    2
    3
    4
    5
    6
    {
      "scripts": {
        "docs:dev": "vuepress dev docs",
        "docs:build": "vuepress build docs"
      }
    }

  • 步骤5: 在终端执行以下三条命令，将默认的临时目录和缓存目录添加到 .gitignore 文件中：

    1
    2
    3
    echo 'node_modules/' >> .gitignore
    echo '.temp' >> .gitignore
    echo '.cache' >> .gitignore

  • 步骤6: 创建你的第一篇文档

    1
    2
    3
    4
    5
    # 创建docs文件夹
    mkdir docs

    # 创建README.md文档
    echo '# Hello VuePress' > docs/README.md

  • 步骤7: 在本地启动服务器来开发你的文档网站

    1
    yarn docs:dev

VuePress 会在 http://localhost:8080 启动一个热重载的开发服务器。当你修改你的 Markdown 文件时，浏览器中的内容也会自动更新。

现在，你应该已经有了一个简单可用的 VuePress 文档网站。接下来，了解一下 VuePress 配置 相关的内容。

配置

配置文件

如果没有任何配置，你的 VuePress 站点仅有一些最基础的功能。为了更好地自定义你的网站，让我们首先在你的文档目录下创建一个 .vuepress 目录，所有 VuePress 相关的文件都将会被放在这里。

百里飞洋：配置文件.vuepress无需手动创建，因为在刚刚执行yarn docs:dev时，已经自动在docs文件夹下创建了.vuepress目录，并且里边还有临时目录和缓存目录.temp和.cache

创建 VuePress 站点的基本配置文件 .vuepress/config.js ，当然也同样支持 TypeScript 配置文件。你可以使用 .vuepress/config.ts 来得到更好的类型提示。

你的项目结构可能是这样：

1
2
3
4
5
6
├─ docs
│  ├─ .vuepress
│  │  └─ config.js
│  └─ README.md
├─ .gitignore
└─ package.json

一个基础的配置文件是这样的：

1
2
3
4
5
6
7
import { defineUserConfig } from 'vuepress'

export default defineUserConfig({
  lang: 'zh-CN',
  title: '你好， VuePress ！',
  description: '这是我的第一个 VuePress 站点',
})

更多配置项可前往官方文档 配置参考 查看所有 VuePress 配置。

客户端配置文件

没这个需求的话这部分可跳过，上面的基础配置文件config.js已经能满足大部分需求了

在大多数情况下，配置文件已经足够帮助你配置好你的 VuePress 站点。不过，有些时候用户们可能希望直接添加一些客户端代码。 VuePress 通过客户端配置文件 client.js 来支持这种需求：

1
2
3
4
5
6
7
├─ docs
│  ├─ .vuepress
│  │  ├─ client.js   <--- 客户端配置文件
│  │  └─ config.js   <--- 配置文件
│  └─ README.md
├─ .gitignore
└─ package.json

一个基础的客户端配置文件是这样的：

1
2
3
4
5
6
7
import { defineClientConfig } from '@vuepress/client'

export default defineClientConfig({
  enhance({ app, router, siteData }) {},
  setup() {},
  rootComponents: [],
})

可以前往 深入 > Cookbook > 客户端配置的使用方法 来了解更多信息。

页面

VuePress 是以 Markdown 为中心的。你项目中的每一个 Markdown 文件都是一个单独的页面。

路由

默认情况下，页面的路由路径是根据你的 Markdown 文件的相对路径决定的。

假设这是你的 Markdown 文件所处的目录结构：

1
2
3
4
5
6
└─ docs
   ├─ guide
   │  ├─ page.md
   │  └─ README.md
   ├─ contributing.md
   └─ README.md

将 docs 目录作为你的 sourceDir(源文件目录) ，例如你在运行 vuepress dev docs 命令。此时，你的 Markdown 文件对应的路由路径为：

相对路径 路由路径
/README.md /
/index.md /
/contributing.md /contributing.html
/guide/README.md /guide/
/guide/page.md /guide/page.html

默认配置下， README.md 和 index.md 都会被转换成 index.html ，并且其对应的路由路径都是由斜杠结尾的。然而，如果你想同时保留这两个文件，就可能会造成冲突。

在这种情况下，你可以设置 pagePatterns 来避免某个文件被 VuePress 处理，例如使用 ['**/*.md', '!**/README.md', '!.vuepress', '!node_modules'] 来排除所有的 README.md 文件。

Frontmatter

Markdown 文件可以包含一个 YAML Frontmatter 。Frontmatter 必须在 Markdown 文件的顶部，并且被包裹在一对三短划线中间。下面是一个基本的示例：

1
2
3
4
5
---
lang: zh-CN
title: 页面的标题
description: 页面的描述
---

你肯定注意到 Frontmatter 中的字段和配置文件中的站点配置.vuepress/config.js十分类似。你可以通过 Frontmatter 来覆盖当前页面的 lang, title, description 等属性。因此，你可以把 Frontmatter 当作页面级作用域的配置。

同样的，VuePress 有一些内置支持的 Frontmatter 字段，而你使用的主题也可能有它自己的特殊 Frontmatter 。

前往 Frontmatter 参考 查看 VuePress 支持的 Frontmatter 配置。

前往 默认主题 > Frontmatter 参考 查看默认主题的 Frontmatter 配置。

内容

页面的主要内容是使用 Markdown 书写的。VuePress 首先会将 Markdown 转换为 HTML ，然后将 HTML 作为 Vue 单文件组件的 <template> 。

借助 markdown-it 和 Vue 模板语法的能力，基础的 Markdown 可以得到很多的扩展功能。接下来，浏览 Markdown 章节来了解 VuePress 中 Markdown 的扩展功能。

Markdown

在阅读本章节之前，请确保你已经对 Markdown 有所了解。如果你还不了解 Markdown ，请先学习一些 Markdown 教程。

语法扩展

VuePress 会使用 markdown-it 来解析 Markdown 内容，因此可以借助于 markdown-it 插件来实现 语法扩展 。

本章节将会介绍 VuePress 内置支持的 Markdown 语法扩展。

你也可以通过 markdown 和 extendsMarkdown 来配置这些内置扩展、加载更多 markdown-it 插件、实现你自己的扩展等。

内置

由 markdown-it 内置支持：

标题锚点

你可能已经注意到，当你把鼠标放在各个章节的标题上时，会显示出一个 # 锚点。点击这个 # 锚点，可以直接跳转到对应章节。

标题锚点扩展由 markdown-it-anchor 支持。

配置参考： markdown.anchor

链接

在你使用 Markdown 的 链接语法 时， VuePress 会为你进行一些转换。

以官方文档的源文件为例：

1
2
3
4
5
6
7
8
9
└─ docs
   └─ zh
      ├─ guide
      │  ├─ getting-started.md
      │  ├─ markdown.md    # <- 比如这个文档
      │  └─ README.md
      ├─ reference
      │  └─ config.md
      └─ README.md

在文档中书写的源码是：

1
2
3
4
5
6
7
8
9
<!-- 相对路径 -->
[首页](../README.md)  
[配置参考](../reference/config.md)  
[快速上手](./getting-started.md)  
<!-- 绝对路径 -->
[指南](/zh/guide/README.md)  
[配置参考 > markdown.links](/zh/reference/config.md#links)  
<!-- URL -->
[GitHub](https://github.com)

VuePress 会转换成的Vue单文件组件代码是：

1
2
3
4
5
6
7
8
<template>
  <RouterLink to="/zh/">首页</RouterLink>
  <RouterLink to="/zh/reference/config.html">配置参考</RouterLink>
  <RouterLink to="/zh/guide/getting-started.html">快速上手</RouterLink>
  <RouterLink to="/zh/guide/">指南</RouterLink>
  <RouterLink to="/zh/reference/config.html#links">配置参考 &gt; markdown.links</RouterLink>
  <a href="https://github.com" target="_blank" rel="noopener noreferrer">GitHub</a>
</template>

渲染到HTML上为：

首页
配置参考
快速上手

指南
配置参考 > markdown.links

GitHub

解释

  • 内部链接会被转换为 <RouterLink> 以便进行 SPA 导航。
  • 指向 .md 文件的内部链接会被转换为目标页面的 路由路径，并且支持绝对路径和相对路径。
  • 外部链接会被添加 target="_blank" rel="noopener noreferrer" 属性。

建议

对于指向内部 Markdown 文件的链接，尽可能使用相对路径而不是绝对路径。

  • 相对路径是指向目标文件的有效链接，在你的编辑器或者代码仓库中浏览源文件时也可以正确跳转。
  • 相对路径在不同 locales 下都是一致的，这样在翻译你的内容时就不需要修改 locale 路径了。

链接扩展是由VuePress内置插件支持的。配置参考：markdown.links

Emoji

你可以在你的 Markdown 内容中输入 :EMOJICODE: 来添加 Emoji 表情。

前往 emoji-cheat-sheet 来查看所有可用的 Emoji 表情和对应代码。

输入

1
VuePress 2 已经发布 :tada: ！

输出

VuePress 2 已经发布 🎉 ！

moji 扩展由 markdown-it-emoji 支持。

配置参考： markdown.emoji

目录

如果你想要把当前页面的目录添加到 Markdown 内容中，你可以使用 [[toc]] 语法。

输入

1
[[toc]]

输出

这里不演示，请看官方文档。

目录中的标题将会链接到对应的 标题锚点，因此如果你禁用了标题锚点，可能会影响目录的功能。

目录扩展由 @mdit-vue/plugin-toc 支持。

配置参考： markdown.toc

代码块

下列代码块扩展是在 Node 端进行 Markdown 解析的时候实现的。这意味着代码块并不会在客户端被处理。

行高亮

你可以在代码块添加行数范围标记，来为对应代码行进行高亮：

输入

1
2
3
4
5
6
7
8
9
10
11
```ts{1,6-8}
import { defaultTheme, defineUserConfig } from 'vuepress'

export default defineUserConfig({
  title: '你好， VuePress',

  theme: defaultTheme({
    logo: 'https://vuejs.org/images/logo.png',
  }),
})
```

输出

这里不演示，请看官方文档。

行数范围标记的例子：

  • 行数范围： {5-8}
  • 多个单行： {4,7,9}
  • 组合： {4,7-13,16,23-27,40}

行高亮扩展是由我们的内置插件支持的，该扩展 Fork 并修改自 markdown-it-highlight-lines。

配置参考： markdown.code.highlightLines

行号

你肯定已经注意到在代码块的最左侧会展示行号。这个功能是默认启用的，你可以通过配置来禁用它。

你可以在代码块添加 :line-numbers / :no-line-numbers 标记来覆盖配置项中的设置。

输入

1
2
3
4
5
6
7
8
9
10
11
```ts
// 行号默认是启用的
const line2 = 'This is line 2'
const line3 = 'This is line 3'
```

```ts:no-line-numbers
// 行号被禁用
const line2 = 'This is line 2'
const line3 = 'This is line 3'
```

输出

这里不演示，请看官方文档。

行号扩展是由我们的内置插件支持的。

配置参考： markdown.code.lineNumbers

添加 v-pre

由于 模板语法可以在 Markdown 中使用，它也同样可以在代码块中生效。

为了避免你的代码块被 Vue 编译， VuePress 默认会在你的代码块添加 v-pre 指令。这一默认行为可以在配置中关闭。（它用来告诉VuePress这是代码块演示）

你可以在代码块添加 :v-pre / :no-v-pre 标记来覆盖配置项中的设置。

模板语法的字符有可能会被语法高亮器解析，比如 “Mustache” 语法（即双花括号）。因此，就像下面的例子一样，在某些语言中 :no-v-pre 可能并不能生效。

如果你无论如何都想在这种语言中使用 Vue 语法，你可以尝试禁用默认的语法高亮，然后在客户端实现你的自定义代码高亮。

输入

1
2
3
4
5
6
7
8
9
10
11
12
13
14
```md
<!-- 默认情况下，这里会被保持原样 -->
1 + 2 + 3 = {{ 1 + 2 + 3 }}
```

```md:no-v-pre
<!-- 这里会被 Vue 编译 -->
1 + 2 + 3 = {{ 1 + 2 + 3 }}
```

```js:no-v-pre
// 由于 JS 代码高亮，这里不会被正确编译
const onePlusTwoPlusThree = {{ 1 + 2 + 3 }}
```

输出

这里不演示，请看官方文档。

导入代码块

你可以使用下面的语法，从文件中导入代码块：

1
2
<!-- 最简单的语法 -->
@[code](../foo.js)

如果你只想导入这个文件的一部分：

1
2
<!-- 仅导入第 1 行至第 10 行 -->
@[code{1-10}](../foo.js)

代码语言会根据文件扩展名进行推断，但我们建议你显式指定：

1
2
<!-- 指定代码语言 -->
@[code js](../foo.js)

实际上，[] 内的第二部分会被作为代码块标记来处理(也就是三个反引号后面的语言标记)，因此在上面 代码块 章节中提到的语法在这里都可以支持：

1
2
<!-- 行高亮 -->
@[code js{2,4-5}](../foo.js)

下面是一个复杂的例子：

  • 导入 '../foo.js' 文件的第 3 行至第 10 行
  • 指定语言为 'js'
  • 对导入代码的第 3 行进行高亮，即 '../foo.js' 文件的第 5 行
  • 禁用行号
1
@[code{3-10} js{3}:no-line-numbers](../foo.js)

需要注意的是，路径别名在导入代码语法中不会生效。你可以通过下面的配置来自行处理路径别名：

1
2
3
4
5
6
7
8
9
10
11
12
import { getDirname, path } from '@vuepress/utils'

const __dirname = getDirname(import.meta.url)

export default {
  markdown: {
    importCode: {
      handleImportPath: (str) =>
        str.replace(/^@src/, path.resolve(__dirname, 'path/to/src')),
    },
  },
}
1
2
<!-- 会被解析至 'path/to/src/foo.js' -->
@[code](@src/foo.js)

导入代码扩展是由我们的内置插件支持的。

配置参考： markdown.importCode

在 Markdown 中使用 Vue

这一章节会介绍 Vue 在 Markdown 中一些基本用法。

可以前往 Cookbook > Markdown 和 Vue SFC 来了解更多内容。

模板语法

我们知道：

  • Markdown 中允许使用 HTML。
  • Vue 模板语法是和 HTML 兼容的。

这意味着， Markdown 中允许直接使用 Vue 模板语法。

输入

1
2
3
一加一等于： {{ 1 + 1 }}

<span v-for="i in 3"> span: {{ i }} </span>

输出

一加一等于： 2

span: 1 span: 2 span: 3

组件

你可以在 Markdown 中直接使用 Vue 组件。

输入

1
这是默认主题内置的 `<Badge />` 组件 <Badge text="演示" />

输出

这里不演示，请看官方文档。（效果是一个右上角的徽标）

前往 内置组件 查看所有内置组件。

前往 默认主题 > 内置组件 查看默认主题中的所有内置组件。

注意事项

非标准的 HTML 标签

非标准的 HTML 标签不会被 Vue 模板编译器识别成原生 HTML 标签。相反，Vue 会尝试将这些标签解析为 Vue 组件，而显然这些组件通常是不存在的。 例如：

  • 已废弃的 HTML 标签，比如 <center> 和 <font> 等。
  • MathML 标签，它们可能会被一些 markdown-it 的 LaTeX 插件用到。

如果你无论如何都要使用这些标签的话，可以尝试下面两种方法之一：

静态资源

我只简单总结，详细内容看官方文档：https://v2.vuepress.vuejs.org/zh/guide/assets.html

相对路径

你可以在你的 Markdown 内容中使用相对路径来引用静态资源：

1
![图片](./image.png)

一般情况下，我们推荐你使用这种方式来引用图片，因为人们通常会把图片放在引用它的 Markdown 文件附近。

Public 文件

你可以把一些静态资源放在 Public 目录中，它们会被复制到最终生成的网站的根目录下。

默认的 Public 目录是 .vuepress/public ，可以通过 public 配置项来修改。

在下列这些情况中，你可能会用到它：

  • 你可能需要提供一些静态资源，但是它们并不直接被你的 Markdown 文件引用，比如 favicon 和 PWA 图标。
  • 你可能想要托管一些共享的静态资源，甚至可能需要在你的网站外部引用它，比如 Logo 图片。
  • 你可能想在你的 Markdown 内容中通过绝对路径来引入图片。

以我们文档的源文件为例，我们把 VuePress 的 Logo 放在了 Public 目录下：

1
2
3
4
5
6
7
└─ docs
   ├─ .vuepress
   |  └─ public
   |     └─ images
   |        └─ hero.png  # <- Logo 文件
   └─ guide
      └─ assets.md       # <- 比如现在我们在这里

我们可以这样在文档页面引用 Logo ：

Input

1
![VuePress Logo](/images/hero.png)

Base Helper

如果你的网站部署在非根路径下，例如 https://foo.github.io/bar/ ，那么你应该把 base 设置为 '/bar/'。显然，此时你的 Public 文件会被部署在 https://foo.github.io/bar/images/hero.png 这样的链接下。

在大多数情况下，你不需要担心这些 Public 文件的引用路径，因为 VuePress 会自动帮你处理 base 前缀：

1
2
<!-- 你不需要给 `/images/hero.png` 手动添加 `/bar/` 前缀 -->
![VuePress Logo](/images/hero.png)

多语言支持

站点多语言配置

要启用 VuePress 的多语言支持，首先需要使用如下的文件目录结构：

1
2
3
4
5
6
7
8
9
10
docs
├─ README.md
├─ foo.md
├─ nested
│  └─ README.md
└─ zh
   ├─ README.md
   ├─ foo.md
   └─ nested
      └─ README.md

然后，在你的 配置文件 中设置 locales 选项：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
export default {
  locales: {
    // 键名是该语言所属的子路径
    // 作为特例，默认语言可以使用 '/' 作为其路径。
    '/': {
      lang: 'en-US',
      title: 'VuePress',
      description: 'Vue-powered Static Site Generator',
    },
    '/zh/': {
      lang: 'zh-CN',
      title: 'VuePress',
      description: 'Vue 驱动的静态网站生成器',
    },
  },
}

如果一个语言没有声明 lang, title, description 或者 head ，VuePress 将会尝试使用顶层配置的对应值。如果每个语言都声明了这些值，那么顶层配置中的对应值可以被省略。

配置参考： locales

主题多语言配置

VuePress 没有限制主题如何提供多语言支持，因此每个主题可能会有不同的多语言配置方式，而且部分主题可能不会提供多语言支持。建议你查看主题本身的文档来获取更详细的指引。

如果你使用的是默认主题，那么它提供多语言支持的方式和上述是一致的：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
import { defaultTheme } from 'vuepress'

export default {
  theme: defaultTheme({
    locales: {
      '/': {
        selectLanguageName: 'English',
      },
      '/zh/': {
        selectLanguageName: '简体中文',
      },
    },
  }),
}

配置参考： 默认主题 > locales

打包工具

打包命令是：

1
yarn docs:build

VuePress 一直以来都在使用 Webpack 作为打包工具来进行网站的开发和构建。从 VuePress v2 开始，我们还支持使用其他的打包工具，并且现在使用 Vite 作为默认的打包工具。当然，你仍然可以选择使用 Webpack 。

更换打包工具

在使用 vuepress 包时，会自动安装和使用 Vite 打包工具。

如果你想改为使用 Webpack 打包工具，那么你可以移除它，改为安装 vuepress-webpack 包：

  • 如果你使用的Yarn
    1
    2
    yarn remove vuepress
    yarn add -D vuepress-webpack@next
  • 如果你使用的NPM
    1
    2
    npm uninstall vuepress
    npm install -D vuepress-webpack@next

实际上， vuepress 包只是 vuepress-vite 包的一个封装而已。

配置打包工具

一般情况下，你不要任何额外配置就可以使用打包工具，因为我们已经帮你配置好了它们。

通过 bundler 配置项，你可以对打包工具进行进阶配置：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
import { viteBundler } from 'vuepress'
// import { webpackBundler } from 'vuepress-webpack'

export default {
  bundler: viteBundler({
    vuePluginOptions: {
      template: {
        compilerOptions: {
          isCustomElement: (tag) => tag === 'center',
        },
      },
    },
  }),
}

你可以参考 打包工具 > Vite 和 打包工具 > Webpack 来查看对应打包工具的所有配置项。

打包后的部署

部署的指南基于以下条件：

  • Markdown 源文件放置在你项目文件夹的 docs 目录；
  • 使用的是默认的打包构建输出目录 (.vuepress/dist) ；
  • 使用 Yarn classic 作为包管理器，当然也可以使用 NPM 。
  • VuePress 作为项目依赖已安装，并已在 package.json 中配置了如下打包脚本：
1
2
3
4
5
{
  "scripts": {
    "docs:build": "vuepress build docs"
  }
}

部署方式有多种，你可能放在自己的服务器站点上，也可能部署在GitHub Pages、GitLab Pages、Vercel、腾讯云开发 CloudBase等地方，不同部署方式详见官方文档：https://v2.vuepress.vuejs.org/zh/guide/deployment.html

主题

VuePress 主题为你提供了布局、样式和其他功能，帮助你专注于 Markdown 内容的写作。

默认主题

VuePress 有一个开箱即用的默认主题，正使用在你当前官方文档上。

如果你不指定要使用的主题，那么就会自动使用默认主题。

为了配置默认主题，你需要在你的配置文件中通过 theme 配置项来使用它：

1
2
3
4
5
6
7
8
9
10
11
12
13
import { defaultTheme } from 'vuepress'

export default {
  theme: defaultTheme({
    // 默认主题配置
    navbar: [
      {
        text: '首页',
        link: '/',
      },
    ],
  }),
}

默认主题为文档网站提供了基础且实用的功能，你可以前往 默认主题配置参考 获取全部的配置列表。

然而，你可能觉得默认主题不够出色，又或者你不想搭建一个文档网站，而是一个其他类型的网站，比如博客。此时，你可以尝试使用社区主题或者创建本地主题。

社区主题

社区用户创建了很多主题，并将它们发布到了 NPM 上。查看主题本身的文档可以获取更详细的指引。

百里飞洋：我就发现了几款写的不错的主题，比如vuepress-theme-qblog、vuepress-theme-quicksand等

本地主题

如果你想要使用自己的自定义主题，但是又不想发布它，你可以创建一个本地主题。前往 深入 > 开发主题 学习如何开发你自己的主题。

插件

借助于 插件 API ， VuePress 插件可以为你提供各种不同的功能。

官方插件参考

常用功能

  • back-to-top给你的站点添加一个 返回顶部 按钮，该插件已经集成到默认主题中。

  • medium-zoom：将 medium-zoom 集成到 VuePress 中，为图片提供可缩放的功能，该插件已经集成到默认主题中。

  • nprogress：将 nprogress 集成到 VuePress 中，在切换到另一个页面时会展示进度条，该插件已经集成到默认主题中。

内容搜索

  • docsearch：将 Algolia DocSearch 集成到 VuePress 中，为你的文档网站提供搜索功能。

  • search：为你的文档网站提供本地搜索能力。

    1
    yarn add @vuepress/plugin-search@next
    1
    2
    3
    4
    5
    6
    7
    8
    9
    import { searchPlugin } from '@vuepress/plugin-search'

    export default {
      plugins: [
        searchPlugin({
          // 配置项
        }),
      ],
    }

PWA

  • pwa：使你的 VuePress 站点成为一个 渐进式 Web 应用 (PWA)

  • pwa-popup提供一个弹窗组件，允许用户手动刷新 PWA Service Worker

语法高亮

社区插件

社区用户创建了很多插件，并将它们发布到了 NPM 上。 VuePress 团队也在 @vuepress Scope 下维护了一些官方插件。查看插件本身的文档可以获取更详细的指引。

一般而言，你需要导入插件并通过配置文件的 plugins 配置项来使用它。举例来说，你可以使用 @vuepress/plugin-google-analytics 来使用 Google Analytics ：

1
2
3
4
5
6
7
8
9
import { googleAnalyticsPlugin } from '@vuepress/plugin-google-analytics'

export default {
  plugins: [
    googleAnalyticsPlugin({
      id: 'G-XXXXXXXXXX'
    }),
  ],
}

大部分插件只能使用一次，如果同一个插件被多次使用，那么只有最后一次会生效。

然而，部分插件是可以被多次使用的（例如 @vuepress/plugin-container），你应该查看插件本身的文档来获取详细指引。

本地插件

如果你想要使用自己的插件，但是又不想发布它，你可以创建一个本地插件。

我们推荐你直接将 配置文件 作为插件使用，因为 几乎所有的插件 API 都可以在配置文件中使用，这在绝大多数场景下都更为方便。

但是如果你在配置文件中要做的事情太多了，你可以考虑将它们提取到单独的插件中，然后在你的配置文件中使用它们：

1
2
3
4
5
6
7
import myPlugin from './path/to/my-plugin.js'

export default {
  plugins: [
    myPlugin(),
  ],
}

前往 深入 > 开发插件 学习如何开发你自己的插件。

从V1版本迁移到V2

我这篇文章是 VuePress(v2.x) 的搭建笔记，从v1.x迁移升级的话请看官方文档：https://v2.vuepress.vuejs.org/zh/guide/migration.html

参考内容：

[1] https://blog.csdn.net/xiaoxianer321/article/details/119548202