GitLab Pages/Vuepress生成项目文档和博客

reco_luan2018-09-09othervuepress

TIP

最近在给公司架构一个新的项目，要求同时写出一个完整的文档，由于正好在浏览vue的GitHub浏览相关项目时，看到了 Vuepress，所以尝试了一把，所以把开发中的积累写下来。

GitLab Pages 原理

首先了解一下GitLab Pages运行的原理。与GitHub不同的是，GitLab需要上传一个 .gitlab-ci.yml 的文件，同时生成的项目文件必须要到 /public 目录中，见详情open in 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

Vuepress

你可以将vuepress安装到全局，也可以将其安装到项目中，我建议选择第二种，后面介绍一下原因

# 创建并进入工程

mkdir project-name
cd project-name

创建 package.json

{
  "scripts": {
    "docs:dev": "vuepress dev docs",
    "docs:build": "vuepress build docs"
  },
  "devDependencies": {
    "vuepress": "^0.14.2"
  }
}

# 安装依赖
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

遇到的坑

其实到这里只是简单的启动了一个vuepress项目，但是你还应该花点时间去仔细阅读一下官网的主题配置，去配置你自己的各种导航，并注意下的页面的设置（主要是主页）。

valine 的引用必须放到mounted中，否则无法编译，报错，window is undefined

修改主题

另外vuepress适合撸项目文档，至于你要用它来写博客，它并没有分类、标签这样的配置，需要你去修改主题，有两种方式：

将主题文件放到 project-name/docs/.vuepress/theme 中，然后创建一个 Layout.vue 文件：

.
└─ .vuepress
   └─ theme
      └─ Layout.vue

这儿和开发一个正常的 Vue 应用程序是一样的。完全取决于你如何组织你的主题。

从依赖中引用主题，要使用 npm 依赖项的主题，请在 .vuepress/config.js 中提供一个 theme 选项：

module.exports = {
  theme: 'reco'
}

郑重推荐 vuepress-theme-reco ，查看展示open in new window 既没有脱离默认主题的简洁，又增加了分类、分页、标签等功能。

# 安装
yarn add vuepress-theme-reco # npm install vuepress-theme-reco

持续更新中。。。

个人博客：午后南杂open in new window