我使用 npm 安装这个失败了，最后用的是 yarn 安装才成功。
npm 我使用过很多版本都不行。
安装
假设在 doc 目录中
使用 yarn init 初始化。
将 VuePress 安装为本地依赖 yarn add -D vuepress
创建你的第一篇文档，VuePress 会以 docs 为文档根目录，所以这个 README.md 相当于主页：
1
| mkdir docs && echo '# Hello VuePress' > docs/README.md
|
在 package.json 中添加一些 scripts
1
2
3
4
5
6
| {
"scripts": {
"docs:dev": "vuepress dev docs",
"docs:build": "vuepress build docs"
}
}
|
启动 yarn docs:dev
VuePress 会在 http://localhost:8080 (opens new window) 启动一个热重载的开发服务器。
配置
1
2
3
4
5
6
| doc
├─ docs
│ ├─ README.md
│ └─ .vuepress
│ └─ config.js
└─ package.json
|
在 .vuepress 文件夹下添加 config.js，配置网站的标题和描述，方便 SEO，并且创建几个文件，目录变成
1
2
3
4
5
6
7
8
9
| doc
├─ docs
│ ├─ README.md
│ └─ .vuepress
│ | └─ config.js
| |_ md
| |_api.md
| |_data.md
└─ package.json
|
我的配置文件变成
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
| module.exports = {
title: 'novel 文档',
description: '小说数据文档',
themeConfig: {
sidebar: [
{
title: "数据对照表",
path: '/md/data',
collapsible: false, // 不折叠
},
{
title: "Restful API",
path: '/md/api',
collapsible: false,
}
]
}
}
|
更换主题
这个主题组织结构更方便一下，可以做到
- 加载
loading
- 切换动画
- 模式切换
- 返回顶部
- 右边侧边栏
现在我们安装 vuepress-theme-reco 执行 yarn add vuepress-theme-reco
然后在 config.js 里引用该主题：
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
| module.exports = {
title: 'novel 文档',
description: '小说数据文档',
theme: 'reco',
themeConfig: {
sidebar: [
{
title: "数据对照表",
path: '/md/data',
collapsible: false, // 不折叠
},
{
title: "Restful API",
path: '/md/api',
collapsible: false,
}
],
subSidebar: 'auto',
}
}
|
部署
因为我的项目是放在我 github 中创建的组织的一个项目中，想要有页面部署，这个项目必须要公开。
我编写了一个上传脚本。
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
| #!/usr/bin/env sh
set -e
npm run docs:build
cd docs/.vuepress/dist
git init
git add -A
git commit -m 'deploy'
git push -f git@***.com:****/doc.git master:gh-pages
cd -
|
每次运行这个脚本就会把文章给推上去。
文件
package.json
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
| {
"name": "doc",
"version": "1.0.0",
"main": "index.js",
"license": "MIT",
"scripts": {
"docs:dev": "vuepress dev docs",
"docs:build": "vuepress build docs"
},
"devDependencies": {
"vuepress": "^1.9.10"
},
"dependencies": {
"vuepress-theme-reco": "^1.6.17"
}
}
|
config.js
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
| module.exports = {
base: '/doc/',
title: 'novel 文档',
description: '小说数据文档',
theme: 'reco',
themeConfig: {
sidebar: [
{
title: "数据对照表",
path: '/md/data',
collapsible: false,
},
{
title: "Restful API",
path: '/md/api',
collapsible: false,
}
],
subSidebar: 'auto',
}
}
|
这里面有一个 base 必须要设置一下，如果你不设置，取其它资源就会变成 https://***.github.io/a.css 只有设置后才会变成 https://***.github.io/doc/a.css 根据自己的情况设置。
还有很多设置，请参考
