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

9/9/2018 vuepress

最近在给公司架构一个新的项目,要求同时写出一个完整的文档,由于正好在浏览 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

# Vuepress

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

# 创建并进入工程

mkdir project-name
cd project-name
1
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
# 安装依赖
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

# 遇到的坑

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

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

# 修改主题

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

  1. 将主题文件放到 project-name/docs/.vuepress/theme 中,然后创建一个 Layout.vue 文件:
.
└─ .vuepress
   └─ theme
      └─ Layout.vue
1
2
3
4

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

  1. 从依赖中引用主题,要使用 npm 依赖项的主题,请在 .vuepress/config.js 中提供一个 theme 选项:
module.exports = {
  theme: 'reco'
}
1
2
3

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

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

# 持续更新中。。。

个人博客:汪荣顶