从零搭建基于VuePress的文档博客
本文会帮助你从头搭建一个简单的 VuePress 文档，并且做一些简单的配置。
一、前提条件
VuePress 需要 Node.js >= 8.6
直接点击下载，或者在DOWNLOADS里按需下载即可
安装好后，查看nodejs版本
二、快速上手
1.创建并进入一个新目录
1
|
mkdir vuepress-milo && cd vuepress-milo
|
2.使用你喜欢的包管理器进行初始化
初始化过程如无特殊需要，一路回车即可
3.将 VuePress 安装为本地依赖
不再推荐全局安装 VuePress
1
|
yarn add -D vuepress # npm install -D vuepress
|
4.创建docs文件夹，和一篇md文档
1
|
mkdir docs && echo '# Hello VuePress' > docs/README.md
|
5.在 package.json 中添加一些 scripts
这里推荐用vscode打开后编辑
这一步骤是可选的，但我们推荐你完成它。
1
2
3
4
5
6
|
{
"scripts": {
"docs:dev": "vuepress dev docs",
"docs:build": "vuepress build docs"
}
}
|
6.在本地启动服务器
1
|
yarn docs:dev # npm run docs:dev
|
三、基本设置
此时的文档博客很丑，下一步我们需要做一些基本配置
1.目录结构设置
VuePress 遵循 “约定优于配置” 的原则，推荐的目录结构如下：
1
2
3
4
5
6
7
8
9
10
11
|
.
├── docs
│ ├── .vuepress
│ │ ├── public
│ │ ├── styles
│ │ │ └── palette.styl
│ │ └── config.js
│ ├── pages
│ └── README.md
│
└── package.json
|
⚠️建议：先把这些都创建好，然后在再写入内容
2.public静态资源目录
docs/.vuepress/public: 静态资源目录，这里我放了图片作为页面主图和偏爱图标
3.重写默认颜色常量
docs/.vuepress/styles/palette.styl: 用于重写默认颜色常量，或者设置新的 stylus 颜色常量
默认是绿色，我这里更改为蓝色
默认页面有点窄，这里更改为900px宽度
1
2
3
4
5
6
|
// 颜色
$accentColor = #235DC8
// 页面设置
.page .theme-default-content:not(.custom){
max-width: 900px!important;
}
|
4.config基本设置
docs/.vuepress/config.js: 配置文件的入口文件，也可以是 YML 或 toml，这里简单设置了网站标题、网站描述、偏爱图标。
1
2
3
4
5
6
7
8
9
10
|
module.exports = {
// 网站标题
title: 'Milo的学习笔记',
// 网站描述
description: '拒绝重复造轮子',
// 偏爱图标
head: [
['link', { rel: 'icon', href: '/aniya.png' }]
],
}
|
5.首页设置
默认的主题提供了一个首页（Homepage）的布局，需要在你的根级 README.md 指定 home: true。以下是一个如何使用的例子：
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
|
---
home: true
heroImage: /aniya.webp
heroText: Milo的学习笔记
tagline: 无比热爱，来日方长！
actionText: Milo的周记 →
actionLink: /
features:
- title: 科研之路
details: 主攻推荐系统、知识图谱，拒绝重复造轮
- title: 目前现状
details: 目前在读研二，本科和研究生都就读于上海工程技术大学，论文撰写中。
- title: 短期规划
details: 完成毕业论文，发表两篇中文核心。
# footer: MIT Licensed | Copyright © 2018-present Evan You
---
|
然后重新启动本地服务
四、pages存放markdown文档
docs/pages 用于存放markdown文件，例如pages中有以下几个md文件
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
|
.
└── pages
├── codes
├── papers
│ ├── kg
│ ├── rs
│ └── rskg
│ ├── AKGE.md
│ ├── DKN.md
│ ├── KGAT.md
│ ├── KGCN.md
│ ├── KGNN-LS.md
│ ├── MKR.md
│ ├── NGCF.md
│ ├── RippleNet.md
│ └── start.md
└── weekly
├── 20220822.md
└── start.md
|
五、导航栏设置
在 docs/.vuepress/config.js 基本设置的基础上，添加导航栏设置
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
|
module.exports = {
// 网站标题
// 网站描述
// 偏爱图标
// 导航栏与侧边栏设置
themeConfig: {
// logo设置
logo: '/aniya.png',
// 导航栏设置
nav: [
{ text: '首页', link: '/' },
{
text: '推荐系统',
ariaLabel: 'recommender systems',
items: [
{ text: '基础知识', link: '/' },
]
},
{
text: '知识图谱',
ariaLabel: 'knowledge graph',
items: [
{ text: '基础知识', link: '/' },
]
},
{
text: '相关论文',
ariaLabel: 'papers',
items: [
{ text: '论文学习', link: '/pages/papers/rskg/start.md' },
{ text: '源码学习', link: '/' },
]
},
{
text: '我的论文',
ariaLabel: 'mypaper',
items: [
{ text: '论文1', link: '/' },
{ text: '论文2', link: '/' },
{ text: '论文3', link: '/' },
]
},
],
//侧边栏设置（后面讲）
}
}
|
然后重新启动本地服务
六、侧边栏设置
在 docs/.vuepress/config.js 基本设置与导航栏设置的基础上，添加侧边栏设置
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
|
module.exports = {
// 网站标题
// 网站描述
// 偏爱图标
// 导航栏与侧边栏设置
themeConfig: {
// logo设置
logo: '/aniya.png',
// 导航栏设置
// 侧边栏设置
sidebar: {
// 周报
'/pages/weekly/':
[
{
title: 'Milo的学习周报', // 必要的
collapsable: true, // 是否可折叠, 默认值是 true,
sidebarDepth: 2, // 侧边栏深度, 默认值是1
children: [
'start',
'20220822',
]
},
],
// 推荐系统&&知识图谱
'/pages/papers/':
[
{
title: '推荐系统&&知识图谱', // 必要的
collapsable: true, // 是否可折叠, 默认值是 true,
sidebarDepth: 2, // 侧边栏深度, 默认值是 1
children: [
'rskg/start',
'rskg/DKN',
'rskg/RippleNet',
'rskg/MKR',
'rskg/KGCN',
'rskg/KGNN-LS',
'rskg/NGCF',
'rskg/AKGE',
'rskg/KGAT',
]
},
{
title: '知识图谱', // 必要的
collapsable: true, // 是否可折叠, 默认值是 true,
sidebarDepth: 2, // 侧边栏深度, 默认值是 1
children: [
]
},
{
title: '推荐系统', // 必要的
collapsable: true, // 是否可折叠, 默认值是 true,
sidebarDepth: 2, // 侧边栏深度, 默认值是 1
children: [
]
},
],
},
}
}
|
然后重新启动本地服务
七、总结
- 安装nodejs
- 创建并进入一个新目录
- 使用你喜欢的包管理器进行初始化
- 将 VuePress 安装为本地依赖
- 创建docs文件夹，和一篇md文档
- 在
package.json 中添加一些 scripts
- 目录结构设置
- public静态资源目录
- 重写默认颜色常量
- config基本设置
- 首页设置
- pages存放markdown文档
- 导航栏设置
- 侧边栏设置
自此所有基本操作都已完成，大家可根据此文章搭建属于自己的文档博客
其他案例
Milo的前端日记
