Leader 讓我做 CMS 幫助中心的技術選型，我擼了 VuePress 和 GitBook，然后選擇...

本文轉載自查看原文 2019-12-10 21:33 1536 vuepress/ gitbook/ vue

前言

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

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

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: 客戶端應用的增強。

注意：

當你想要去自定義 templates/ssr.html 或 templates/dev.html 時，最好基於默認的模板文件來修改，否則可能會導致構建出錯。
還有就是筆者的 templates/ssr.html 和 templates/dev.html 是有添加如下這一行代碼的：

<meta id="referrer" name="referrer" content="never" />

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

1.5 評論

評論功能用了 GitTalk。

1.5.1 申請一個 OAuth App

具體實踐如下：

首先登錄你的 GitHub 賬號，然后點擊進入Settings。

點擊 OAuth Apps , Register a new application 或者 New OAuth App 。

輸入信息。

應用信息說明：Client ID && Client Secret

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

創建評論組件

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>

使用評論組件

理論上，我們在每個 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"
  },

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

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

比如我的：

1.6 部署到 Github pages

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

創建一個deploy.sh

touch 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 -

設置 package.json

{
    "scripts": {
        "deploy": "bash deploy.sh"
      },
}

發布

npm run deploy   // 即可自動構建部署到 github 上。

訪問自己的域名，比如筆者的：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 的意思：

title：網站標題
author：網站作者
description：網站功能描述
language：網站使用語言
styles：網站額外配置的樣式表
plugins：網站使用的插件
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

相同點

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

不同點

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

結論