GitBook - 快速打造可留言的部落格

jsliang發表於2019-05-22

Create by jsliang on 2019-05-20 14:43:41
Recently revised in 2019-05-22 18:01:09

本文將介紹如何安裝 GitBook、如何起 GitBook 服務、如何配置 GitBook，以及到最後的部署到 GitHub Pages 或者部署到個人雲伺服器。

小夥伴們如果覺得不錯可以到 jsliang 的文件庫為 jsliang 點個 star，謝謝~

【2019-08-16】Hello 小夥伴們，由於 jsliang 對文件庫進行了重構，這篇文章中的一些連結可能失效，而 jsliang 缺乏精力維護掘金這邊的舊文章，對此深感抱歉。請需要獲取最新文章的小夥伴，點選上面的 GitHub 地址，去文件庫檢視調整後的文章。

下面是最終效果，歡迎評論留言~

LiangJunrong.github.io

一目錄

不折騰的前端，和鹹魚有什麼區別

目錄
一目錄
二前言
三 GitBook 常用指令
四 GitBook 外掛配置
五 GitBook 打包部署
六總結

二前言

返回目錄

由於平時喜歡使用 MarkDown 編寫文件，無意中在工作上暴露了自己會使用 MarkDown 的 “優點”，所以上週日（2019-05-19）被抓苦力，叫去將公司 WIKI 轉成 GitBook。

後面回到租房自己又玩了下，表示深深被吸引了，這也太好用了吧！

所以在這裡安利給小夥伴們，大家一起 happy 下。

三 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

首先，我們為電腦配置 GitBook，在終端中直接敲：npm i gitbook-cli -g，電腦會配置好 GitBook。

由於 Mac 可能會有許可權限制，所以需要執行 sudo npm i gitbook-cli -g

然後，我們找個空資料夾，初始化一個 GitBook 專案：gitbook init，目錄會生成一個 README.md 內容檔案和一個 SUMMARY.md 目錄檔案。

- GitBook
 - README.md
 - SUMMARY.md
複製程式碼

README.md
# 號表示一級標題，詳情可自行檢視 MarkDown 語法

# Introduction


複製程式碼

SUMMARY.md
[連結](連結地址) 表示跳轉連結，即 GitBook 會根據你的 SUMMARY 自動幫你生成左側選單欄的目錄

# Summary

* [Introduction](README.md)


複製程式碼

最後，我們在終端輸入 gitbook serve 即可開啟一個 localhost:4000 的服務，請在瀏覽器中輸入 http://localhost:4000 即可訪問服務。

四 GitBook 外掛配置

返回目錄

僅僅只有個搜尋功能的 GitBook 怎麼可能吸引 jsliang！，外掛的配置才是 GitBook 的核心！！！

下面我們開始配置 GitBook 外掛。

首先，給目錄中新增一個 book.json 檔案：

- GitBook
 - README.md
 - SUMMARY.md
 - book.json
複製程式碼

然後，我們配置下 book.json：

book.json

{
  "title": "jsliang 的文件庫",
  "author": "樑峻榮 - jsliang",
  "description": "jsliang 的文件庫. 裡面包含了個人撰寫的所有前端文章，例如 Vue、React,、ECharts、微信小程式等……",
  "language": "zh-hans",
  "styles": {
    "website": "./public-repertory/css/gitbook-configure.css"
  },
  "plugins": [
    "theme-comscore",
    "prism",
    "-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": "LiangJunrong",
          "repo": "document-library", 
          "type": "star",
          "count": true,
          "size": "small"
        }, 
        {
          "user": "LiangJunrong",
          "width": "160", 
          "type": "follow", 
          "count": true,
          "size": "small"
        }
      ]
    },
    "donate": {
      "button": "打賞",
      "alipayText": "支付寶打賞",
      "wechatText": "微信打賞",
      "alipay": "https://github.com/LiangJunrong/document-library/blob/master/public-repertory/img/seek-reward.jpg?raw=true",
      "wechat": "https://github.com/LiangJunrong/document-library/blob/master/public-repertory/img/seek-reward.png?raw=true"
    },
    "prism": {
      "css": [
        "prismjs/themes/prism-solarizedlight.css"
      ],
      "lang": {
        "shell": "bash"
      }
    },
    "tbfed-pagefooter": {
      "copyright":"Copyright &copy jsliang.top 2019",
      "modify_label": "該檔案修訂時間：",
      "modify_format": "YYYY-MM-DD HH:mm:ss"
    },
    "baidu-tongji": {
      "token": "55e7dfe47f4dc1c018d4042fdfa62565"
    },
    "anchor-navigation-ex": {
      "showLevel": false
    }
  }
}
複製程式碼

最後，我們安裝下 book.json 中配置的外掛：gitbook install，並把 jsliang 的文件庫的內容複製過來，修改下 SUMMARY.md，重新啟動專案：gitbook serve。

當然，這需要你配置下 SUMMARY.md 檔案，不過這應該對你來說不成問題。

4.1 book.json

返回目錄

現在，我們講解下 book.json 的意思：

title：網站標題
author：網站作者
description：網站功能描述
language：網站使用語言
styles：網站額外配置的樣式表
plugins：網站使用的外掛
pluginsConfig：網站使用的外掛的額外配置

下面主要講解下 styles 和 plugins。

4.2 gitbook - styles

返回目錄

有的時候，GitBook 會自帶一些你不需要的樣式，例如側邊欄的 由 GitBook 提供支援 等，我們可以通過設定 CSS 來讓它隱藏掉：

.gitbook-link {
  display: none !important;
}
.summary .divider {
  display: none !important;
}
複製程式碼

4.3 gitbook - plugins

返回目錄

plugins 即外掛的意思，有的 plugins 的配置，因為需要使用者自行決定需要使用哪些功能，所以需要再額外配置下 pluginsConfig。

下面我們先列 plugins 清單，再逐個講解功能實現：

外掛 1 - theme-comscore

theme-comscore：為 GitBook 新增好看的樣式，它會使 Table 表單等變得更加好看。

配置方法

"plugins": [
  "theme-comscore"
]
複製程式碼

參考效果：

外掛 2 - prism

prism：為 GitBook 的 Code 新增更好看的樣式，使用它的時候記得遮蔽 GitBook 預設的 highlight 外掛，即通過（-highlight 表示，下面出現 - 的外掛也一樣）

配置方法

"plugins": [
  "prism",
  "-highlight"
],
"pluginsConfig": {
  "prism": {
    "css": [
      "prismjs/themes/prism-solarizedlight.css"
    ],
    "lang": {
      "shell": "bash"
    }
  }
}
複製程式碼

參考效果：

外掛 3 - copy-code-button

copy-code-button：給 GitBook 的 Code 新增複製功能，可以一鍵複製程式碼塊的所有程式碼。

配置方法

"plugins": [
  "copy-code-button"
]
複製程式碼

參考效果：

外掛 4 - search-pro

search-pro：由於 GitBook 支援的搜尋，對於中文不太好。新增該外掛後，對搜尋結果能用高亮來顯示，非常強大。當然，由於取締了預設的搜尋功能，所以需要遮蔽 search 和 lunr

配置方法

"plugins": [
  "search-pro",
  "-search",
  "-lunr"
]
複製程式碼

參考效果：

外掛 5 - expandable-chapters

expandable-chapters：由於側邊欄標題是預設全部展開的，所以這個外掛會讓它具有展開收縮功能。

配置方法

"plugins": [
  "expandable-chapters"
]
複製程式碼

參考效果：

外掛 6 - splitter

splitter：讓側邊欄的寬度可以自行拖動。

配置方法

"plugins": [
  "splitter"
]
複製程式碼

參考效果：

外掛 7 - -sharing

-sharing：去掉 GitBook 預設的分享功能。由於它預設的一些推特，臉書都需要翻牆，而我們做的是中文站點，所以將分享功能全部關閉掉。

配置方法

"plugins": [
  "-sharing"
]
複製程式碼

參考效果：

外掛 8 - github-buttons

github-buttons：給 GitBook 新增 GitHub 的圖示，來顯示 follow 和 stars。

配置方法

"plugins": [
  "github-buttons"
],
"pluginsConfig": {
  "github-buttons": {
  "buttons": [
    {
      "user": "LiangJunrong",
      "repo": "document-library", 
      "type": "star",
      "count": true,
      "size": "small"
    }, 
    {
      "user": "LiangJunrong",
      "width": "160", 
      "type": "follow", 
      "count": true,
      "size": "small"
    }
  ]
  }
}
複製程式碼

參考效果：

外掛 9 - donate

donate：給底部配置一個打賞模組，使用者可以點選進行支付寶、微信打賞等。

配置方法

"plugins": [
  "donate"
],
"pluginsConfig": {
  "donate": {
    "button": "打賞",
    "alipayText": "支付寶打賞",
    "wechatText": "微信打賞",
    "alipay": "https://github.com/LiangJunrong/document-library/blob/master/public-repertory/img/seek-reward.jpg?raw=true",
    "wechat": "https://github.com/LiangJunrong/document-library/blob/master/public-repertory/img/seek-reward.png?raw=true"
  }
}
複製程式碼

參考效果：

外掛 10 - tbfed-pagefooter

tbfed-pagefooter：給 GitBook 每個頁面新增頁尾，這樣就可以知道這些檔案的 copyright 以及修改時間等。

配置方法

"plugins": [
  "tbfed-pagefooter"
],
"pluginsConfig": {
  "tbfed-pagefooter": {
    "copyright":"Copyright &copy jsliang.top 2019",
    "modify_label": "該檔案修訂時間：",
    "modify_format": "YYYY-MM-DD HH:mm:ss"
  }
}
複製程式碼

參考效果：

外掛 11 - baidu-tongji

baidu-tongji：給 GitBook 的站點新增百度統計，這樣使用者的訪問數量可以通過百度統計檢視到。

配置方法

"plugins": [
  "baidu-tongji"
],
"pluginsConfig": {
  "baidu-tongji": {
    "token": "55e7dfe47f4dc1c12345678fdfa62565"
  }
}
複製程式碼

外掛 12 - anchor-navigation-ex

anchor-navigation-ex：根據 # ## ### 自動生成選單，並新增跳轉到頂部效果。

配置方法

"plugins": [
  "anchor-navigation-ex"
],
"pluginsConfig": {
  "anchor-navigation-ex": {
    "showLevel": false
  }
}
複製程式碼

參考效果：

外掛 13 - gitalk

gitalk：給頁面新增評論功能，這些評論內容會新增到 GitHub 倉庫的 Issue 上。

首先，這不是一個外掛，Gitalk 是一個基於 GitHub Issue 和 Preact 開發的評論外掛。

然後，我們在 MessageBoard.md（即我們需要新增評論區的頁面）中新增對應的程式碼：

<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/gitalk@1/dist/gitalk.css">
<script src="https://cdn.jsdelivr.net/npm/gitalk@1/dist/gitalk.min.js"></script>
<div id="gitalk-container"></div>
<script>
  var gitalk = new Gitalk({
    "clientID": "需要補充的 clientID",
    "clientSecret": "需要補充的 clientSecret",
    "repo": "document-library",
    "owner": "LiangJunrong",
    "admin": ["LiangJunrong"],
    "id": location.pathname,      
    "distractionFreeMode": false  
  });
  gitalk.render("gitalk-container");
</script>
複製程式碼