超详细动手搭建一个Vuepress站点及开启PWA与自动部署

五一以前就想写一篇关于Vuepress的文章,结果朋友结婚就不了了之了。javascript

记得最后必定要看注意事项！css

Vuepress介绍

官网：https://vuepress.vuejs.org/html

相似hexo一个极简的静态网站生成器,用来写技术文档不能在爽。固然搭建成博客也不成问题。前端

Vuepress特色

响应式,也能够自定义主题与hexo相似
内置markdown(还增长了一些扩展),而且能够在其使用Vue组件
Google Analytics 集成
PWA 自动生成Service Worker

快速上手

安装

初始化项目vue

yarn init -y
# 或者 npm init -y

安装vuepressjava

yarn add -D vuepress
# 或者 npm install -D vuepress

全局安装vuepresswebpack

yarn global add vuepress
# 或者 npm install -g vuepress

新建一个docs文件夹nginx

mkdir docs

设置下package.jsongit

{
  "scripts": {
    "docs:dev": "vuepress dev docs",
    "docs:build": "vuepress build docs"
  }
}

写做

yarn docs:dev # 或者：npm run docs:dev

也就是运行开发环境,直接去docs文件下书写文章就能够,打开http://localhost:8080/能够预览github

image

构建

build生成静态的HTML文件,默认会在 .vuepress/dist 文件夹下

yarn docs:build # 或者：npm run docs:build

基本配置

在 .vuepress目录下新建一个config.js,他导出一个对象

一些配置能够参考官方文档,这里我配置经常使用及必须配置的

网站信息

module.exports = { title: '游魂的文档', description: 'Document library', head: [ ['link', { rel: 'icon', href: `/favicon.ico` }], ], }

导航栏配置

module.exports = { themeConfig: { nav: [ { text: '主页', link: '/' }, { text: '前端规范', link: '/frontEnd/' }, { text: '开发环境', link: '/development/' }, { text: '学习文档', link: '/notes/' }, { text: '游魂博客', link: 'https://www.iyouhun.com' }, // 下拉列表的配置 { text: 'Languages', items: [ { text: 'Chinese', link: '/language/chinese' }, { text: 'English', link: '/language/English' } ] } ] } }

如图：

image

侧边栏配置

能够省略.md扩展名,同时以 / 结尾的路径将会被视为 */README.md

module.exports = { themeConfig: { sidebar: { '/frontEnd/': genSidebarConfig('前端开发规范'), } } }

上面封装的genSidebarConfig函数

function genSidebarConfig(title) { return [{ title, collapsable: false, children: [ '', 'html-standard', 'css-standard', 'js-standard', 'git-standard' ] }] }

支持侧边栏分组(能够用来作博客文章分类) collapsable是当前分组是否展开

module.exports = { themeConfig: { sidebar: { '/note': [ { title:'前端', collapsable: true, children:[ '/notes/frontEnd/VueJS组件编码规范', '/notes/frontEnd/vue-cli脚手架快速搭建项目', '/notes/frontEnd/深刻理解vue中的slot与slot-scope', '/notes/frontEnd/webpack入门', '/notes/frontEnd/PWA介绍及快速上手搭建一个PWA应用', ] }, { title:'后端', collapsable: true, children:[ 'notes/backEnd/nginx入门', 'notes/backEnd/CentOS如何挂载磁盘', ] }, ] } } }

如图：

成品图

默认主题修改

主题色修改

在.vuepress目录下的建立一个override.styl文件

$accentColor = #3eaf7c // 主题色 $textColor = #2c3e50 // 文字颜色 $borderColor = #eaecef // 边框颜色 $codeBgColor = #282c34 // 代码背景颜色

自定义页面类

有时须要在不一样的页面应用不一样的css,能够先在该页面中声明

--- pageClass: custom-page-class ---

而后在override.styl中书写

.theme-container.custom-page-class { /* 特定页面的 CSS */ }

PWA设置

设置serviceWorker为true,而后提供Manifest 和 icons,能够参考我以前的《PWA介绍及快速上手搭建一个PWA应用》

module.exports = { head: [ ['link', { rel: 'icon', href: `/favicon.ico` }], //增长manifest.json ['link', { rel: 'manifest', href: '/manifest.json' }], ], serviceWorker: true, }

部署上线

设置基础路径

在config.js设置base
例如：你想要部署在https://foo.github.io 那么设置base为/,base默认就为/,因此能够不用设置
想要部署在https://foo.github.io/bar/,那么 base 应该被设置成 "/bar/"

module.exports = { base: '/documents/', }

base 将会自动地做为前缀插入到全部以 / 开始的其余选项的连接中,因此你只须要指定一次。

构建与自动部署

用gitHub的pages或者coding的pages均可以,也能够搭建在本身的服务器上。
将dist文件夹中的内容提交到git上或者上传到服务器就好

yarn docs:build # 或者：npm run docs:build

另外能够弄一个脚本,设置持续集成,在每次 push 代码时自动运行脚本

deploy.sh

#!/usr/bin/env sh # 确保脚本抛出遇到的错误 set -e # 生成静态文件 npm run docs:build # 进入生成的文件夹 cd docs/.vuepress/dist # 若是是发布到自定义域名 # echo 'www.example.com' > CNAME git init git add -A git commit -m 'deploy' # 若是发布到 https://<USERNAME>.github.io # git push -f git@github.com:<USERNAME>/<USERNAME>.github.io.git master # 若是发布到 https://<USERNAME>.github.io/<REPO> git push -f git@github.com:<USERNAME>/<REPO>.git master:gh-pages cd -

注意事项(坑)

把你想引用的资源都放在.vuepress目录下的public文件夹
给git仓库绑定了独立域名后,记得修改base路径
设置侧边栏分组后默认会自动生成上/下一篇连接
设置了自动生成侧边栏会把侧边栏分组覆盖掉
设置PWA记得开启SSL