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

简介

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.mdindex.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 语法扩展。

你也可以通过 markdownextendsMarkdown 来配置这些内置扩展、加载更多 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 PagesGitLab PagesVercel腾讯云开发 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-qblogvuepress-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