一步步搭建 VuePress 及優化【插件系列】

介紹

在以前爲了搭建 VuePress 的文檔，順帶製做了視頻教程，現在準備再次搭建一個 VuePress 的項目，一看本身的視頻居然有五個小時，天吶，我只是須要過一遍而已，因此從新整理成文檔吧，萬一未來又要用呢……

固然，若是您以爲文字版不夠直觀，能夠前往觀看視頻版： 【☛ 視頻地址 ☚】 ，當時錄製完本地測試後以爲聲音大小還能夠，結果一套錄完了才發現聲音很小，因此推薦帶上耳機。

VuePress 文檔示例

插件列表

爲了方便的統一管理 plugin，須要對 docs/.vuepress/config.js 進行配置：

// docs/.vuepress/config.js
const pluginConf = require('../../config/pluginConf.js');

module.exports = {
  plugins: pluginConf,
}

插件的不少服務都須要對 head 標籤進行修改：

// docs/.vuepress/config.js
const headConf = require('../../config/headConf.js');

module.exports = {
  head: headConf,
}

以後就能夠去修改 config/pluginConf.js 和 config/headConf.js 文件了。

1. PWA

具體的 PWA 配置介紹能夠看 官方文檔，對應的 視頻（8:20） 。

VuePress 的版本會致使使用方式不一致，此處僅介紹 1.x 版本：

安裝：

yarn add -D @vuepress/plugin-pwa@next
# OR npm install -D @vuepress/plugin-pwa@next

使用：

module.exports = {
  '@vuepress/pwa': {
    serviceWorker: true,
    updatePopup: {
      message: "發現新內容可用.",
      buttonText: "刷新",
      // 自定義彈窗
      // popupComponent: 'MySWUpdatePopup',
    }
  },
};

PWA NOTES：

serviceWorker 選項僅僅用來控制 service worker，爲了讓你的網站徹底地兼容 PWA，你須要在 .vuepress/public 提供 Manifest 和 icons，更多細節，請參見 MDN docs about the Web App Manifest. 此外，只有您可以使用 SSL 部署您的站點時才能啓用此功能，由於 service worker 只能在 HTTPs 的 URL 下注冊。

​ -- VuePress 官網

由於使用的 Github Pages 服務，因此即便使用 CNAME 後也依然保持 SSL 狀態。

Manifest 第六個視頻其實存在一些問題，在第九個 視頻 中解決了，利用 App Manifest Generator 直接生成便可。

參考示例：

{
  "name": "飛躍高山與大洋的魚",
  "short_name": "山與海",
  "description": "飛躍高山與大洋的魚的文檔",
  "theme_color": "#2196f3",
  "background_color": "#2196f3",
  "display": "standalone",
  "start_url": "index.html",
  "icons": [
    {
      "src": "/icons/icon-72x72.png",
      "sizes": "72x72",
      "type": "image/png"
    },
    {
      "src": "/icons/icon-96x96.png",
      "sizes": "96x96",
      "type": "image/png"
    },
    {
      "src": "/icons/icon-128x128.png",
      "sizes": "128x128",
      "type": "image/png"
    },
    {
      "src": "/icons/icon-144x144.png",
      "sizes": "144x144",
      "type": "image/png"
    },
    {
      "src": "/icons/icon-152x152.png",
      "sizes": "152x152",
      "type": "image/png"
    },
    {
      "src": "/icons/icon-192x192.png",
      "sizes": "192x192",
      "type": "image/png"
    },
    {
      "src": "/icons/icon-384x384.png",
      "sizes": "384x384",
      "type": "image/png"
    },
    {
      "src": "/icons/icon-512x512.png",
      "sizes": "512x512",
      "type": "image/png"
    }
  ]
}

還須要獲取一下 favicons 等：

// config/headConf.js

module.exports = [
  ['link', { rel: 'apple-touch-icon', href: '/apple-touch-icon.png' }],
  ['link', { rel: 'icon', href: '/favicon-32x32.png' }],
  ['link', { rel: 'manifest', href: '/manifest.json' }],
  ['meta', { name: 'theme-color', content: '#ffffff' }],
];

2. 評論（待修改）

評論須要按照你的需求來：若是你但願全部評論能夠在 Github 可見，那麼使用 Gitalk 吧，正好有一篇新鮮出爐的文章；若是你想要全部非 Github 用戶也能夠評論的話可使用 Valine，視頻 地址。

這邊利用的其實 主題的繼承 ，經過修改 VuePress 的默認主題來實現須要的功能，在製做視頻的時候官網尚未對這個詳細的描述，此次更新發現有了新的介紹，因爲時間關係及下一個項目不須要評論因此暫時延期處理：

首先修改默認主題下的 Page 組件（這意味着你不能隨便使用 npm install 了）：

<!-- node_modules/@vuepress/theme-default/components/Page.vue  -->

      </p>
    </div>

    <slot name="bottom"/>
    <Valine></Valine>
  </main>
</template>

接着建立 Valine 組件，對於評論組件有如下要求：

1. 在 README.md 文件中能夠關閉評論；
2. 在不一樣的路由顯示不一樣的評論

<!-- docs/.vuepress/components/Valine.vue -->

<template>
  <div class="ValineComment" v-if="comment">
    <hr>
    <span :id="page.path" class="leancloud-visitors" :data-flag-title="page.title">
      <em class="post-meta-item-text">文章閱讀量 </em>
      <i class="leancloud-visitors-count">1000000+</i>
    </span>
    <div id="vcomments"></div>
  </div>
</template>

<script>
export default {
  computed: {
    comment: function () {
      let { comment } = this.$frontmatter;
      if (typeof comment === 'undefined') {
        return true;
      }
      return comment;
    },
    page: function () {
      let { path = '/', title = '首頁' } = this.$page;
      return { path, title };
    }
  },
  mounted() {
    this.renderValine()
  },
  watch: {
    '$route': {
      handler: function (to, from) {
        if (to.path !== from.path) {
          this.$nextTick(() => {
            this.renderValine();
          })
        }
      }
    }
  },
  methods: {
    renderValine() {
      if (typeof window !== 'undefined') {
        this.window = window;
        window.AV = require('leancloud-storage');
      }
      const secretKeyConf = require('../../../config/secretKeyConf.js');
      const Valine = require('valine');
      new Valine({
        el: '#vcomments' ,
        appId: secretKeyConf.appId,
        appKey: secretKeyConf.appKey,
        notify:false,
        verify:false,
        avatar:'retro',
        path: window.location.pathname,
        meta: ['nick','mail','link'],
        pageSize: 10,
        visitor: true,
        placeholder: '歡迎留言...' 
      });
    }
  }
}
</script>

<style lang="stylus" scoped>
.ValineComment {
  padding 0 2rem;
}
.leancloud-visitors {
  display inline-block
  margin-bottom 1rem;
}
</style>

3. Back-to-top

具體的 Back-to-top 配置介紹能夠看 官方文檔 。

安裝：

yarn add -D @vuepress/plugin-back-to-top@next
# OR npm install -D @vuepress/plugin-back-to-top@next

使用：

// config/pluginConf.js

module.exports = {
  '@vuepress/back-to-top': true,
};

效果圖：

4. google-analytics

具體的 google-analytics 配置介紹能夠看 官方文檔 。

你須要去 Google 獲取對應的 key 。

安裝：

yarn add -D @vuepress/plugin-google-analytics@next
# OR npm install -D @vuepress/plugin-google-analytics@next

使用：

// config/pluginConf.js
// 此處引伸出的隱私問題在最後有說明

const secretKeyConf = require('./secretKeyConf.js');

module.exports = {
  '@vuepress/google-analytics': {
    'ga': secretKeyConf.ga
  }
};

效果：

0. 隱藏私密信息

按理說，會了 git 基本上都知道這個功能，然而依然有不少人把本身的私密信息（如密碼）上傳到 Github 倉庫，對應 視頻（29:00） 。

主要是使用 .gitignore 文件來忽略你要上傳的文件，舉個例子：

// config/secretKeyConf.js

module.exports = secretKeyConf = {
  appId: 'xxxxxx',
  appKey: 'xxxxxx',
  ga: 'xxxxxx',
  googleSearchConsole: 'xxxxxx',
}

將 config/secretKeyConf.js 追加到 .gitignore 文件中

# secretKeyConf
secretKeyConf.js

最後

爲了方便閱讀，因此將內容進行了劃分：

1. VuePress 初始化及發佈
2. VuePress 插件系列
3. VuePress 自動化

參考資料

1. VuePress 官網
2. Valine 官網