藉助 VuePress 和 GitBook ，10 分鐘即可免費部署你的靜態部落格網站

  • 2019 年 12 月 19 日
  • 筆記

前言

因為自己平時經常寫部落格，也有部落格網站，所以 Leader 叫我做一個 CMS 的幫助中心的技術選型，CMS 的幫助中心的功能：是通過文章來教用戶如何使用我們的項目。

所以筆者要做一個靜態網站的技術選型，筆者把網上流行的 VuePress 和 GitBook 兩種方式都嘗試了一下，並做了對比，這裡寫篇文章總結一下，順便把自己的部落格網站重作一遍，哈哈。

優惠消息：雙 12，阿里伺服器新用戶 1 折，老用戶 5 折：筆者覺得每個開發者都應該擁有自己的網站和伺服器，這可是很酷的事情，學習 Linux、跑跑腳本、建站、搭部落格啥的都行，現在阿里雲的伺服器只需要 89元 一年，一起參與瓜分 60 萬現金，優惠只剩下最後幾天了，需要的趕快上車了，錯過還需要再等一年。

1. VuePress

1.1 簡介

VuePress 是 Vue 驅動的靜態網站生成器。

簡潔至上

以 Markdown 為中心的項目結構，以最少的配置幫助你專註於寫作。

Vue 驅動

享受 Vue + webpack 的開發體驗，可以在 Markdown 中使用 Vue 組件，又可以使用 Vue 來開發自定義主題。

高性能

VuePress 會為每個頁面預渲染生成靜態的 HTML，同時，每個頁面被載入的時候，將作為 SPA 運行。

1.2 效果

首頁：

評論：

效果詳情請看：https://biaochenxuying.github.io/blog/ 。

1.3 簡單使用

像數 1, 2, 3 一樣容易

# 安裝  yarn global add vuepress # 或者：npm install -g vuepress    # 創建項目目錄  mkdir vuepress-starter && cd vuepress-starter    # 新建一個 markdown 文件  echo '# Hello VuePress!' > README.md    # 開始寫作  vuepress dev .    # 構建靜態文件  vuepress build .

1.4 目錄結構

VuePress 遵循 「約定優於配置」 的原則，推薦的目錄結構如下：

├── docs  │   ├── .vuepress (可選的)  │   │   ├── components (可選的)  │   │   ├── theme (可選的)  │   │   │   └── Layout.vue  │   │   ├── public (可選的)  │   │   ├── styles (可選的)  │   │   │   ├── index.styl  │   │   │   └── palette.styl  │   │   ├── templates (可選的, 謹慎配置)  │   │   │   ├── dev.html  │   │   │   └── ssr.html  │   │   ├── config.js (可選的)  │   │   └── enhanceApp.js (可選的)  │   │  │   ├── README.md  │   ├── guide  │   │   └── README.md  │   └── config.md  │  └── package.json

注意：請留意目錄名的大寫。

  • docs/.vuepress: 用於存放全局的配置、組件、靜態資源等。
  • docs/.vuepress/components: 該目錄中的 Vue 組件將會被自動註冊為全局組件。
  • docs/.vuepress/theme: 用於存放本地主題。
  • docs/.vuepress/styles: 用於存放樣式相關的文件。
  • docs/.vuepress/styles/index.styl: 將會被自動應用的全局樣式文件，會生成在最終的 CSS 文件結尾，具有比默認樣式更高的優先順序。
  • docs/.vuepress/styles/palette.styl: 用於重寫默認顏色常量，或者設置新的 stylus 顏色常量。
  • docs/.vuepress/public: 靜態資源目錄。
  • docs/.vuepress/templates: 存儲 HTML 模板文件。
  • docs/.vuepress/templates/dev.html: 用於開發環境的 HTML 模板文件。
  • docs/.vuepress/templates/ssr.html: 構建時基於 Vue SSR 的 HTML 模板文件。
  • docs/.vuepress/config.js: 配置文件的入口文件，也可以是 YML 或 toml。
  • docs/.vuepress/enhanceApp.js: 客戶端應用的增強。

注意：

  1. 當你想要去自定義 templates/ssr.html 或 templates/dev.html 時，最好基於 默認的模板文件 來修改，否則可能會導致構建出錯。
  2. 還有就是筆者的 templates/ssr.html 和 templates/dev.html 是有添加如下這一行程式碼的：
<meta id="referrer" name="referrer" content="never" />

因為筆者的圖片都是存在簡書上的，所以為了可以訪問第三方圖床的圖片，才添加了這句程式碼，如果你的圖片是存在本地的，去掉這句程式碼即可，至於具體原因請看筆者寫的文章：前端解決第三方圖片防盜鏈的辦法 - html referrer 訪問圖片資源403問題 。

  1. 筆者的目錄也是按官方推薦的來的，如下：

1.5 評論

評論功能用了 GitTalk。

1.5.1 申請一個 OAuth App

具體實踐如下：

  1. 首先登錄你的 GitHub 帳號，然後點擊進入Settings。
  1. 點擊 OAuth Apps , Register a new application 或者 New OAuth App 。
  1. 輸入資訊。

image.png

  1. 應用資訊說明：Client ID && Client Secret

創建成功有 Client ID 和 Client Secret ，保存下來，後面我們會用到。

  1. 創建評論組件

Vuepress 默認 .vuepress / components 文件夾下的組件會全局註冊，因此我們創建一個 comment 組件。

gittalk.css 請點擊 這裡

<template>    <div class="gitalk-container">      <div id="gitalk-container"></div>    </div>  </template>  <script>  export default {    name: 'comment',    data() {      return {};    },    mounted() {      let body = document.querySelector('.gitalk-container');      let script = document.createElement('script');      script.src = 'https://cdn.jsdelivr.net/npm/gitalk@1/dist/gitalk.min.js';      body.appendChild(script);      script.onload = () => {        const commentConfig = {          clientID: '你的clientID',          clientSecret: '你的clientSecret',          repo: '你的倉庫名稱',          owner: '你的用戶名',          // 這裡接受一個數組，可以添加多個管理員，可以是你自己          admin: ['管理用戶名'],          // id 用於當前頁面的唯一標識，一般來講 pathname 足夠了，          // 但是如果你的 pathname 超過 50 個字元，GitHub 將不會成功創建 issue，此情況可以考慮給每個頁面生成 hash 值的方法.          id: location.pathname,          distractionFreeMode: false,        };        const gitalk = new Gitalk(commentConfig);        gitalk.render('gitalk-container');      };    },  };  </script>  <style>  @import '../css/gittalk.css';  </style>
  1. 使用評論組件

理論上，我們在每個 markdown 文件里直接加入這個組件即可，但是每次都添加有點麻煩，還是讓 node 來幫我們吧

根目錄創建 build 文件夾, 創建三個文件 addComponents.js, delComponents.js, findMarkdown.js, 分別程式碼如下：

// addComponents.js  const fs = require("fs");  const findMarkdown = require("./findMarkdown");  const rootDir = "./docs";    findMarkdown(rootDir, writeComponents);    function writeComponents(dir) {      if (!/README/.test(dir)) {          fs.appendFile(dir, `n n <comment/> n `, err => {              if (err) throw err;              console.log(`add components to ${dir}`);          });      }  }  
// delComponents.js  const fs = require("fs");  const findMarkdown = require("./findMarkdown");  const rootDir = "./docs";    findMarkdown(rootDir, delComponents);    function delComponents(dir) {      fs.readFile(dir, "utf-8", (err, content) => {          if (err) throw err;            fs.writeFile(              dir,              content.replace(/n n <comment/> n /g, ""),              err => {                  if (err) throw err;                  console.log(`del components from ${dir}`);              }          );      });  }  
// findMarkdown.js  const fs = require("fs");    function findMarkdown(dir, callback) {      fs.readdir(dir, function(err, files) {          if (err) throw err;          files.forEach(fileName => {              let innerDir = `${dir}/${fileName}`;              if (fileName.indexOf(".") !== 0) {                  fs.stat(innerDir, function(err, stat) {                      if (stat.isDirectory()) {                          findMarkdown(innerDir, callback);                      } else {                          // 跳過readme 文件，當然你也可以自行修改                          if (/.md$/.test(fileName) && !/README/.test(fileName))                              callback(innerDir);                      }                  });              }          });      });  }  module.exports = findMarkdown;

修改 package.json 的 scripts, 先為每個 md 文件添加組件，然後打包，最後再一一刪除 markdown 中的 comment 組件。

"build": "node ./builds/addComponents.js && vuepress build docs && node ./builds/delComponents.js",

筆者的項目裡面是把添加了二條命令的，比如 npm run dev:md 和 npm run build:md 才是有評論組件的。

"scripts": {      "dev": "vuepress dev docs",      "dev:md": "node ./builds/addComponents.js && vuepress dev docs && node ./builds/delComponents.js",      "docs:dev": "vuepress dev docs",      "build": "vuepress build docs",      "build:md": "node ./builds/addComponents.js && vuepress build docs && node ./builds/delComponents.js",      "docs:build": "vuepress build docs",      "delay": "bash delay.sh",      "test": "echo "Error: no test specified" && exit 1"    },

想要怎樣的打包命令，自己修改就行。

  1. 注意：如果你的文章的評論要和 github 的 issues 的同步的話，還要在 issues 的 label 里添加相應的 pathname 和 gitalk，其中 pathname 就是評論組件裡面的 location.pathname 。

比如我的：

1.6 部署到 Github pages

當我們將文檔寫好後就到了我們最關心的地方了，怎麼將打包後的程式碼推送到遠程倉庫的 gh-pages 分支上。

  1. 創建一個deploy.sh
touch deploy.sh
  1. 編寫腳本
#!/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 [email protected]:<USERNAME>/<USERNAME>.github.io.git master    # 如果發布到 https://<USERNAME>.github.io/<REPO>  # git push -f [email protected]:<USERNAME>/<REPO>.git master:gh-pages    cd -
  1. 設置 package.json
{      "scripts": {          "deploy": "bash deploy.sh"        },  }
  1. 發布
npm run deploy   // 即可自動構建部署到 github 上。
  1. 訪問自己的域名，比如筆者的：https://biaochenxuying.github.io/blog/ 。

詳情移步 vuepress 官網 vuepress.vuejs.org。

2. GitBook

效果：

效果詳情請看：http://biaochenxuying.cn:2021。

2.1 GitBook 常用指令

  • 安裝 GitBook：npm i gitbook-cli -g
  • 初始化 GitBook 項目：gitbook init
  • 安裝 GitBook 依賴：gitbook install
  • 開啟 GitBook 服務：gitbook serve
  • 打包 GitBook 項目：gitbook build
  • GitBook 命令行查看：gitbook -help
  • GitBook 版本查看：gitbook -V

2.2 簡單上手

然後，我們找個空文件夾，初始化一個 GitBook 項目。

  • gitbook init 初始化 README.md 和 SUMMARY.md 兩個文件.
  • gitbook build 本地構建但不運行服務，默認輸出到 _book/ 目錄.
  • gitbook serve 本地構建並運行服務，默認訪問 http://localhost:4000 實時預覽.
- GitBook   - README.md   - SUMMARY.md
  • README.md 是默認首頁文件，相當於網站的首頁 index.html ,一般是介紹文字或相關導航鏈接.
  • SUMMARY.md 是默認概括文件，主要是根據該文件內容生成相應的目錄結構，同 README.md 一樣都是被 gitbook init 初始化默認創建的重要文件.
  • _book 是默認的輸出目錄，存放著原始 markdown 渲染完畢後的 html 文件，可以直接打包到伺服器充當靜態網站使用。一般是執行 gitbook build 或 gitbook serve 自動生成的.
  • book.json 是配置文件，用於個性化調整 gitbook 的相關配置，如定義電子書的標題、封面、作者等資訊。雖然是手動創建但一般是必選的.
  • GLOSSARY.md 是默認的辭彙表，主要說明專業辭彙的詳細解釋，這樣閱讀到專業辭彙時就會有相應提示資訊，也是手動創建但是可選的.
  • LANGS.md 是默認的語言文件，用於國際化版本翻譯和 GLOSSARY.md 一樣是手動創建但是可選的.

book.json 的意思：

  1. title：網站標題
  2. author：網站作者
  3. description：網站功能描述
  4. language：網站使用語言
  5. styles：網站額外配置的樣式表
  6. plugins：網站使用的插件
  7. pluginsConfig：網站使用的插件的額外配

筆者的 book.json:

{    "title": "夜盡天明的部落格",    "author": "biaochenxuying",    "description": "大前端技術為主，讀書筆記、隨筆、理財為輔，做個終身學習者。",    "language": "zh-hans",    "plugins": [      "-highlight",      "copy-code-button",      "search-pro",      "-search",      "-lunr",      "expandable-chapters",      "splitter",      "-sharing",      "github-buttons",      "donate",      "tbfed-pagefooter",      "baidu-tongji",      "anchor-navigation-ex"    ],    "pluginsConfig": {      "github-buttons": {        "buttons": [          {            "user": "biaochenxuying",            "repo": "blog",            "type": "star",            "count": true,            "size": "small"          },          {            "user": "biaochenxuying",            "width": "160",            "type": "follow",            "count": true,            "size": "small"          }        ]      },      "donate": {        "button": "打賞",        "wechatText": "微信打賞",        "wechat": "https://camo.githubusercontent.com/ee094d402f957e5d656a399b9dc50ff8c010114e/68747470733a2f2f75706c6f61642d696d616765732e6a69616e7368752e696f2f75706c6f61645f696d616765732f31323839303831392d666661623762643234643038633030642e6a7065673f696d6167654d6f6772322f6175746f2d6f7269656e742f7374726970253743696d61676556696577322f322f772f31323430"      },      "tbfed-pagefooter": {        "copyright":"Copyright &copy biaochenxuying.cn 2019",        "modify_label": "該文件修訂時間：",        "modify_format": "YYYY-MM-DD HH:mm:ss"      },      "baidu-tongji": {        "token": "XXXXX"      },      "anchor-navigation-ex": {        "showLevel": false      }    }  }

2.3 插件

插件的配置可以說是 GitBook 的核心。

詳情可以看 GitBook - 快速打造可留言的部落格，這裡就不展開講了。

3. VuePress VS GitBook

相同點

  1. 目前只支援 markdown 格式，圖片、影片 等靜態資源可以保存在本地，或者保存到允許訪問的第三方服務商（如七牛雲）；
  2. 如果是 world 文檔或者 html 格式，要轉換成 md 格式才行。
  3. 找了幾個 world 文檔轉換成 md 格式的工具，都不好用，特別是有原文檔有圖片的時候。

不同點

  1. GitBook 的配置成本很小，可以本地編輯，然後直接部署；GitBook 官方還有個在線編輯器，不過內容要存在 GitBook 的伺服器上。
  2. VuePress 的配置成本稍稍大一點，不過可以使用 Vue 的語法與組件，訂製化更自由一點，而且 VuePress 中編寫 Vue 和平時一樣，學習成本幾乎為零，可以本地用 VsCode 編輯，然後直接命令行部署。

結論

  1. 都要用 markdown 語法來寫文章，markdown 也就幾個常用語法而已，非常簡單上手。
  2. 非技術人員推薦用 GitBook，技術人員推薦用 VuePress，特別是前端技術人員。
  3. 個人更喜歡 VuePress 。

4. 項目源碼

本文中使用 VuePress 和 GitBook 的搭建的完整示例程式碼都已經上傳到 GitHub 上了，可以自行下載來用。

只要把其中的一些配置資訊換成自己的就行，比如 倉庫、Client ID && Client Secret、作者等。

源碼地址：https://github.com/biaochenxuying/blog 。

其中 VuePress 和 GitBook 的示例程式碼都在 blog-gitbook 和 blog-vuepress 裡面了。

這次需求的結果

令筆者吐血的是：花了 3 天搞的調研，最後 leader 沒有採用 ?，還是用回了 功能很重的 wordpress。

因為非技術人員要用起來的話，學習成本是比較大的 ?，比如要學 markdown 語法、ide 編輯器、基本的打包命令、可能還要學 git ，而非技術人員編輯文檔時，一般是用 wps 的 ?。

比較欣慰的是：筆者做完調研後，自己的部落格網站也能用上了，哈哈。

最後

推薦閱讀：GitHub 上能挖礦的神仙技巧 - 如何發現優秀開源項目，估計很多人都不知道的技巧，甚至很多高級工程師都不知道。

參考文章：為你的 VuePress 部落格添加 GitTalk 評論

Tags:

VirMach 便宜 VPS