Leader 讓我作 CMS 幫助中心的技術選型，我擼了 VuePress 和 GitBook，而後選擇...

時間 2019-12-16

標籤 leader cms 幫助中心技術選型 vuepress gitbook 而後選擇欄目 CMS 简体版

原文原文鏈接

前言

由於本身平時常常寫博客，也有博客網站，因此 Leader 叫我作一個 CMS 的幫助中心的技術選型，CMS 的幫助中心的功能：是經過文章來教用戶如何使用咱們的項目。css

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

優惠消息。前端

筆者以爲每一個開發者都應該擁有本身的網站和服務器，這但是很酷的事情，學習 Linux、跑跑腳本、建站、搭博客啥的都行。vue

1. VuePress

1.1 簡介

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

簡潔至上webpack

以 Markdown 爲中心的項目結構，以最少的配置幫助你專一於寫做。git

Vue 驅動github

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

高性能npm

VuePress 會爲每一個頁面預渲染生成靜態的 HTML，同時，每一個頁面被加載的時候，將做爲 SPA 運行。

1.2 效果

首頁：

評論：

效果詳情請看：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 上。
複製代碼

訪問本身的域名，好比筆者的：biaochenxuying.github.io/blog/ 。

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

2. GitBook

效果：

效果詳情請看：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 編輯，而後直接命令行部署。

結論