最近在给公司架构一个新的项目，要求同时写出一个完整的文档，由于正好在浏览vue的GitHub浏览相关项目时，看到了 Vuepress，所以尝试了一把，所以把开发中的积累写下来。
# GitLab Pages 原理
首先了解一下GitLab Pages运行的原理。与GitHub不同的是，GitLab需要上传一个 .gitlab-ci.yml 的文件，同时生成的项目文件必须要到 /public 目录中，见详情 (opens new window)。
## .gitlab-ci.yml
image: node:9.11.1
pages:
cache:
paths:
- node_modules/
script:
- npm install
- npm run docs:build
artifacts:
paths:
- public
only:
- master
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
# Vuepress
你可以将vuepress安装到全局，也可以将其安装到项目中，我建议选择第二种，后面介绍一下原因
# 创建并进入工程
mkdir project-name
cd project-name
1
2
3
4
2
3
4
创建package.json
{
"scripts": {
"docs:dev": "vuepress dev docs",
"docs:build": "vuepress build docs"
},
"devDependencies": {
"vuepress": "^0.14.2"
}
}
1
2
3
4
5
6
7
8
9
2
3
4
5
6
7
8
9
# 安装依赖
yarn install # 或 npm install
# 创建并进入docs目录
mkdir docs
cd docs
# 创建一个 markdown 文件
echo '# Hello VuePress' > README.md
# 启动项目
yarn docs:dev # 或 npm run docs:dev
# 编译项目至 '/project-name/public' 中
yarn docs:dev # 或 npm run docs:dev
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
2
3
4
5
6
7
8
9
10
11
12
13
14
15
# 遇到的坑
其实到这里只是简单的启动了一个vuepress项目，但是你还应该花点时间去仔细阅读一下官网的主题配置，去配置你自己的各种导航，并注意下的页面的设置（主要是主页）。
- valine 的引用必须放到mounted中，否则无法编译，报错，window is undefined
# 修改主题
另外vuepress适合撸项目文档，至于你要用它来写博客，它并没有分类、标签这样的配置，需要你去修改主题，有两种方式：
- 将主题文件放到
project-name/docs/.vuepress/theme中，然后创建一个Layout.vue文件：
.
└─ .vuepress
└─ theme
└─ Layout.vue
1
2
3
4
2
3
4
这儿和开发一个正常的 Vue 应用程序是一样的。完全取决于你如何组织你的主题。
- 从依赖中引用主题，要使用 npm 依赖项的主题，请在
.vuepress/config.js中提供一个 theme 选项：
module.exports = {
theme: 'reco'
}
1
2
3
2
3
郑重推荐 vuepress-theme-reco ，查看 展示 (opens new window) 既没有脱离默认主题的简洁，又增加了分类、分页、标签等功能。
# 安装
yarn add vuepress-theme-reco # npm install vuepress-theme-reco
1
2
2
# 持续更新中。。。
作者个人博客：午后南杂 (opens new window)