本文基于 VuePress v2.0.0-rc15 版本,使用默认的内置主题

开始构建

你可以按照官方文档的步骤创建,也可以参考本文。并且,官方还提供了 StackBlitz 可以直接在浏览器体验 VuePress。

注意

VuePress 同时支持读取 docs 下的 README.mdindex.md,但都转为 index.html,因此本文只给出 index.md 示例,浪子也推荐使用该方式。本文写的都是较为简单的配置,也可以编写函数完成高级配置,请自行查询资料。

两种创建方式

1
npm init vuepress vuepress-site
1
2
3
4
5
6
7
8
9
10
11
mkdir vuepress-site && cd vuepress-site
# 初始化项目
npm init
# 安装 vuepress
npm install -D vuepress@next
# 安装打包工具和主题
npm i -D @vuepress/bundler-vite@next @vuepress/theme-default@next
# 创建 docs 文件夹和配置文件夹
mkdir docs && mkdir docs/.vuepress
# 创建 VuePress 的配置文件
touch docs/.vuepress/config.ts

这样,一个简单的 VuePress 的网站就基本成型了,该文件夹的结构基本如下:

1
2
3
4
5
6
├─ docs
│ ├─ .vuepress
│ │ └─ config.ts
│ └─ index.md
├─ .gitignore
└─ package.json
  • docs/.vuepress 是 vuepress 存放配置文件的路径,公共静态资源默认路径为 docs/.vuepress/public
  • 配置文件支持 ts 和 js,推荐使用 ts 获得支持 IDE 的智能提示。

添加运行脚本命令

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

网站首页配置

docs/index.md
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
---
# 标记该页是主页
home: true
# 首页图片的 URL
heroImage: /image/logo.png
heroText: 首页标题,如果不设置,则默认使用站点 title
tagline: 首页标语,如果不设置,则默认使用站点 description
# 显示的按钮
actions:
- text: 开始
link: 相对于 docs 的文章链接,当然,你也可以放置一个 URL
type: primary
- text: 快速上手
link: 相对于 docs 的文章链接,当然,你也可以放置一个 URL
type: secondary
# 复制官网的例子
features:
- title: 简洁至上
details: Markdown 为中心的项目结构,以最少的配置帮助你专注于写作。
- title: Vue 驱动
details: 享受 Vue 的开发体验,可以在 Markdown 中使用 Vue 组件,又可以使用 Vue 来开发自定义主题。
- title: 高性能
details: VuePress 会为每个页面预渲染生成静态的 HTML,同时,每个页面被加载的时候,将作为 SPA 运行。

footer: 页脚
# 是否允许页脚中使用 HTML 如果设置为 true ,那么 footer 会被作为 HTML 代码处理。
footerHtml: false
---

这样,主页内容就完成了。接下来修改网站配置文件 docs/.vuepress/config.ts

docs/.vuepress/config.ts
1
2
3
4
5
6
7
8
9
10
export default defineUserConfig({
// 网站 title,首页缺失 heroText 默认使用这个
title: "我的 VuePress 站点",
// 网站 desc,首页缺失 tagline 默认使用这个
description: "使用 vuepress2 搭建的小站点,会是什么效果呢?真令人期待!",

// 默认的打包工具
bundler: viteBundler(),
theme: defaultTheme(),
})

然后运行 npm run docs:dev 并访问 http://localhost:8080 查看效果。

进阶配置

单语言站点配置

docs/.vuepress/config.ts
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
export default defineUserConfig({
// https://vuepress.vuejs.org/zh/guide/deployment.html#github-pages
// base 选项与本地运行无关,只和部署有关
base: "/repo/",
// 本地启动时预览的端口,默认 8080,可以自己修改
port: 8080,

// 网站 meta 信息
// favicon
head: [["link", {rel: "icon", href: "/images/logo.png"}]],
title: "Title",
description: "Description",

bundler: viteBundler(),

// 主题配置
theme: defaultTheme({
// 也可以设置为一个 URL,例如:https://gitlab.com/foo/image.jpg
logo: "/image/logo.png",

// 仓库配置,可以是 github、gitee、gitlab 等,会自动识别
// GitHub 仓库,也可以设置为一个 URL,例如:https://gitlab.com/foo/bar
repo: "username/repo",
// 源文件所在分支
docsBranch: "main",
// 源文件所在的仓库的目录名称
docsDir: "docs",

// 替换一些英文的默认值 https://ecosystem.vuejs.press/zh/themes/default/locale.html#selectlanguagetext
// 默认值: "Edit this page"
editLinkText: "编辑本页",
// 默认值: "Last Updated"
lastUpdatedText: "最后修改",
// 默认值: "Contributors"
contributorsText: "贡献者",
// 默认值: "toggle color mode"
toggleColorMode: "昼夜模式切换",
// 默认值: "Back to home"
backToHome: "返回首页",
// 侧边栏配置,显示列表深度 1,包含 <h2>,默认值为 2 显示到 <h3> 层级
sidebarDepth: 1,

// 侧边栏显示内容
sidebar: [
{
// 大标题,相当于分组,children 中的文档都属于此分组,该标题默认不可点击
text: "指南",
// 该项配置 children 的文章目录是否折叠,默认为 false 即不折叠
// 为 true 时自动折叠,不可与 link 共存
collapsible: true,
children: [
"/guide/index.md",
"/guide/如何学好算法.md",
"/guide/如何学好数据结构.md",
],
},
{
// 只要设置了 link 选项,text 就可以有点击事件了,点击跳转 link 配置的路径
text: "进阶",
// 不可与 collapsible 共存
link: "/advanced/算法1.md",
children: [
"/advanced/数据结构.md",
"/advanced/算法1.md",
],
},
],
})
})

此时,目录结构应为:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
├─ docs
│ ├─ .vuepress
│ │ └─ public
│ │ └─ config.js
│ ├─ guide
│ │ └─ index.md
│ │ └─ 如何学好算法.md
│ │ └─ 如何学好数据结构.md
│ ├─ advanced
│ │ └─ 数据结构.md
│ │ └─ 算法1.md
│ └─ index.md
├─ .gitignore
└─ package.json

多语言站点配置

多语言配置也很简单,下面只给一个示例,不再进行额外的说明了。

docs/.vuepress/config.ts
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
export default defineUserConfig({

head: [["link", {rel: "icon", href: "/images/logo.png"}]],
title: "Title",
description: "Description",

// 多语言配置,locales 为每种语言设置不同语言设计站点 meta 描述信息
// 如果一个语言没有声明 lang, title, description 或者 head,VuePress 将会尝试使用顶层配置的对应值。
// 如果每个语言都声明了这些值,那么顶层配置中的对应值可以被省略。
locales: {
// / 在 vuepress 中是特例,代表网站默认使用的语言配置
"/": {
lang: "zh",
title: "多语言配置——中文大标题",
description: "爆竹声中一岁除 春风送暖入屠苏",
head: []
},
// 推荐使用 / 结尾,否则导航进入时可能出现 404
"/en/": {
lang: "en",
title: "English Language Title",
description: "i dont speak english",
head: []
}
// 其它语言
...
},

bundler: viteBundler(),

theme: defaultTheme({
// 也可以设置为一个 URL,例如:https://gitlab.com/foo/image.jpg
logo: "/image/logo.png",
// 仓库配置,可以是 github、gitee、gitlab 等,vuepress 会自动识别
// GitHub 仓库,也可以设置为一个 URL,例如:https://gitlab.com/foo/bar
repo: "username/repo",
// 仓库中源文件所在分支
docsBranch: "main",
// 仓库中源文件的所在目录
docsDir: "docs",
// 侧边栏配置,显示列表深度 1,包含 <h2>;默认值 2 <h3>
sidebarDepth: 1,

// 为不同语言配置不同的显示标签,对不同语言的用户更加友好。
// 这里 locales 配置需要根据网站的 locales 的键来配置
locales: {
// 中文配置
"/": {
selectLanguageText: "选择语言",
selectLanguageName: "简体中文",
// 替换一些英文的默认值
// 默认值: "Edit this page"
editLinkText: "修改此页",
// 默认值: "Last Updated"
lastUpdatedText: "最后修改",
// 默认值: "Contributors"
contributorsText: "贡献者",
// 默认值: "toggle color mode"
toggleColorMode: "昼夜模式切换",
// 默认值: "Back to home"
backToHome: "返回首页",
prev: "上一页",
next: "下一页",

// 侧边栏
sidebar: [
{
text: "指南",
children: [
"/guide/index.md",
"/guide/如何学好算法.md",
"/guide/如何学好数据结构.md",
],
},
]
},

// 英文配置
"/en/": {
selectLanguageName: "English",
sidebar: [
{
text: "Guide",
children: [
"/guide/index.md",
],
},
]
}
// other
...
}
}),
}

此时,目录的结构为:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
├─ docs
│ ├─ .vuepress
│ │ └─ public
│ │ └─ config.ts
│ ├─ en
│ │ └─ guide
│ │ │ └─ index.md
│ │ └─ index.md
│ ├─ guide
│ │ └─ index.md
│ │ └─ 如何学好算法.md
│ │ └─ 如何学好数据结构.md
│ ├─ advanced
│ │ └─ 数据结构.md
│ │ └─ 算法1.md
│ └─ index.md
├─ .gitignore
└─ package.json

VitePress

引用 VitePress 官网的一段话

VitePress 灵感来源于 VuePress。最初的 VuePress 基于 Vue 2 和 webpack。借助 Vue 3 和 Vite,VitePress 提供了更好的开发体验、更好的生产性能、更精美的默认主题和更灵活的自定义 API。

VitePress 和 VuePress 之间的 API 区别主要在于主题和自定义。如果使用的是带有默认主题的 VuePress 1,迁移到 VitePress 应该相对简单。

VuePress 2 我们也投入了精力,它也支持 Vue 3 和 Vite,与 VuePress 1 的兼容性更好。但是,并行维护两个 SSG 是难以持续的,因此 Vue 团队决定将重点放在 VitePress,作为长期的主要 SSG 选择推荐。

区别

所有的选项都基于默认主题、默认配置

选项 VuePress 2.0.0.RC15 VitePress 1.3
静态资源目录 docs/.vuepress/public docs/public
数学公式、Github标签支持、代码块聚焦 不支持 支持
主页 md 除了 frontmatter 外是否可以有正文内容 支持 不支持(其实是支持,但是没有样式)

VitePress 默认的功能就很丰富,不过 VuePress 有插件生态,不仅有主题插件还有额外的功能插件。具体可以查看各自官网文档的展示效果选择自己喜欢的使用。


本站由 江湖浪子 使用 Stellar 1.29.1 主题创建。
本博客所有文章除特别声明外,均采用 CC BY-NC-SA 4.0 许可协议,转载请注明出处。