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

# 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适合撸项目文档,至于你要用它来写博客,它并没有分类、标签这样的配置,需要你去修改主题,有两种方式:

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

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

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

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

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

# 持续更新中。。。

个人博客:午后南杂 (opens new window)

Last Updated: 5/30/2020, 12:30:10 AM