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

发表于 |




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

> 五一之前就想写一篇关于Vuepress的文章,结果朋友结婚就不了了之了。
>
> 记得最后一定要看注意事项！

## Vuepress介绍

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

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

## Vuepress特点

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

## 快速上手

### 安装

初始化项目

yarn init -y
# 或者 npm init -y
1
2
3
4
5
6

安装vuepress

    <pre class="hljs shell"><code class="shell">yarn add -D vuepress
    <span class="hljs-meta">#<span class="bash"> 或者 npm install -D vuepress
    </span></span></code>


全局安装vuepress

yarn global add vuepress
    # 或者 npm install -g vuepress
    
1
2
3
4
5

新建一个docs文件夹

    <pre class="hljs shell"><code class="shell">mkdir docs
    </code>


设置下package.json

    
{
      “scripts”: {
        “docs:dev”: “vuepress dev docs”,
        “docs:build”: “vuepress build docs”
      }
    }
    
1
2
3
4
5

### 写作

<pre class="hljs shell"><code class="shell">yarn docs:dev # 或者：npm run docs:dev
</code>


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

    

    

    

    


    
image

    ### 构建

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

    
yarn docs:build # 或者：npm run docs:build
    
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

    ## 基本配置

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

一些配置可以参考[官方文档](https://link.jianshu.com?t=https%3A%2F%2Fvuepress.vuejs.org%2Fconfig%2F%23base),这里我配置常用及必须配置的

    ### 网站信息

    <pre class="hljs javascript"><code class="javascript"><span class="hljs-built_in">module.exports = {
      <span class="hljs-attr">title: <span class="hljs-string">'游魂的文档',
      <span class="hljs-attr">description: <span class="hljs-string">'Document library',
      <span class="hljs-attr">head: [
        [<span class="hljs-string">'link', { <span class="hljs-attr">rel: <span class="hljs-string">'icon', <span class="hljs-attr">href: <span class="hljs-string">`/favicon.ico` }],
      ],
    }
    </span></span></span></span></span></span></span></span></span></span></span></code>


    ### 导航栏配置

    
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’ }
            ]
          }
        ]
      }
    }
    
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

如图：

    <div class="image-package">
    <div class="image-container">
    <div class="image-container-fill"> 
    <div class="image-view" data-width="556" data-height="83">![](http://pangguoming.com/blog/images/d0397c5a-09c6-4d33-bdd8-fd95ecb6d468.jpg)

    <div class="image-caption">image

    ### 侧边栏配置

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

    <pre class="hljs javascript"><code class="javascript"><span class="hljs-built_in">module.exports = {
      <span class="hljs-attr">themeConfig: {
        <span class="hljs-attr">sidebar: {
          <span class="hljs-string">'/frontEnd/': genSidebarConfig(<span class="hljs-string">'前端开发规范'),
        }
      }
    }
    </span></span></span></span></span></code>


上面封装的genSidebarConfig函数

    
function genSidebarConfig(title) {
      return [{
        title,
        collapsable: false,
        children: [
          ‘’,
          ‘html-standard’,
          ‘css-standard’,
          ‘js-standard’,
          ‘git-standard’
        ]
      }]
    }
    
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31

支持侧边栏分组(可以用来做博客文章分类) collapsable是当前分组是否展开

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


如图：

    

    

    

    


    
成品图

    ## 默认主题修改

    ### 主题色修改

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

    
$accentColor = #3eaf7c // 主题色
    $textColor = #2c3e50 // 文字颜色
    $borderColor = #eaecef // 边框颜色
    $codeBgColor = #282c34 // 代码背景颜色
    
1
2
3
4
5
6
7
8
9

    ### 自定义页面类

有时需要在不同的页面应用不同的css,可以先在该页面中声明

    <pre class="hljs yaml"><code class="yaml"><span class="hljs-meta">---
    <span class="hljs-attr">pageClass: <span class="hljs-string">custom-page-class
    <span class="hljs-meta">---
    </span></span></span></span></code>


然后在override.styl中书写

    
.theme-container.custom-page-class {
      / 特定页面的 CSS /
    }
    
1
2
3
4
5
6
7
8
9
10
11
12
13
14

    ## PWA设置

设置serviceWorker为true,然后提供Manifest 和 icons,可以参考我之前的《[PWA介绍及快速上手搭建一个PWA应用](https://www.jianshu.com/p/fad8aa9e277f)》

    <pre class="hljs javascript"><code class="javascript"><span class="hljs-built_in">module.exports = {
      <span class="hljs-attr">head: [
        [<span class="hljs-string">'link', { <span class="hljs-attr">rel: <span class="hljs-string">'icon', <span class="hljs-attr">href: <span class="hljs-string">`/favicon.ico` }],
        <span class="hljs-comment">//增加manifest.json
        [<span class="hljs-string">'link', { <span class="hljs-attr">rel: <span class="hljs-string">'manifest', <span class="hljs-attr">href: <span class="hljs-string">'/manifest.json' }],
      ],
      <span class="hljs-attr">serviceWorker: <span class="hljs-literal">true,
    }
    </span></span></span></span></span></span></span></span></span></span></span></span></span></span></span></code>


    ## 部署上线

    ### 设置基础路径

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

    
module.exports = {
      base: ‘/documents/‘,
    }
    
1
2
3
4
5
6
7
8
9
10

`base` 将会自动地作为前缀插入到所有以 `/` 开始的其他选项的链接中,所以你只需要指定一次。

    ### 构建与自动部署

用[gitHub](https://link.jianshu.com?t=https%3A%2F%2Fgithub.com)的pages或者[coding](https://link.jianshu.com?t=https%3A%2F%2Fcoding.net%2Fr%2FO5YOFA)的pages都可以,也可以搭建在自己的服务器上。  
 将`dist`文件夹中的内容提交到git上或者上传到服务器就好

    <pre class="hljs shell"><code class="shell">yarn docs:build # 或者：npm run docs:build
    </code>


> 另外可以弄一个脚本,设置持续集成,在每次 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://.github.io
    # git push -f git@github.com:/.github.io.git master

    # 如果发布到 https://.github.io/
    git push -f git@github.com:/.git master:gh-pages

    cd -
    `

    ## 注意事项(坑)

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

感谢支持原创技术分享