Gitbook的實用技巧專欄

---

專欄目錄

• Gitbook介紹
• Gitbook安裝
• Gitbook簡單使用
• Gitbook插件介紹
• Gitbook錯誤處理

專欄詳情

Gitbook

Gitbook介紹

GitBook 是一個基於 Node.js 的命令行工具
可用 Github/Git 和 Markdown 組合製做成精美的電子文檔
GitBook支持輸出多種文檔格式：
    * 靜態站點: GitBook默認輸出格式, 生成的靜態站點
    * PDF: 須要安裝 gitbook-pdf
    * eBook: 須要安裝ebook-convert
    * 單HTML網頁: 支持將內容輸出爲單頁HTML, 不過通常用在將電子書格式轉換爲PDF或eBook的中間過程
    * JSON: 通常用於電子書的調試或元數據提取
使用GitBook製做電子書, 必備兩個文件: README.md[主頁面] SUMMARY.md[側邊欄頁面]
複製代碼

Gitbook安裝

# 安裝Gitbook須要node.js做爲前提依賴, 安裝時確保主機已經存在node.js
node -v

# 安裝Gitbook多版本託管工具, 可同時託管多個Gitbook版本, 且下載最新版的Gitbook驅動
npm install gitbook-cli -g

# 驗證下載是否成功
gitbook -V

# 下載歷史版本[下載3.0.0版本]
# 3.2.3版本確保爲不可用版本, 推薦使用3.0.0
gitbook fetch 3.0.0

# 進入到你的項目文件夾, 初始化一個Gitbook項目
gitbook init

# 生成README.md 和 SUMMARY.md 兩個基本文件

# 啓動服務
gitbook serve

# 指定gitbook版本啓動
gitbook serve --gitbook=3.0.0

# 獲取幫助
gitbook --help

# 卸載指定版本Gitbook[卸載3.2.3版本]
gitbook uninstall 3.2.3

# 生成靜態網頁
gitbook build

# 指定gitbook版本生成靜態文件，若是本地沒有將先下載
gitbook build --gitbook=3.0.0

# 列出本地全部的gitbook版本
gitbook ls

# 列出遠程可用的gitbook版本
gitbook ls-remote

# 更新到gitbook的最新版本
gitbook update

# 安裝配置依賴插件
gitbook install

# 指定log的級別
gitbook build --log=debug

# 輸出錯誤信息
gitbook builid --debug
複製代碼

Gitbook簡單使用

在 README.md 中撰寫Gitbook項目的主界面, 而 SUMMARY.md 是Gitbook界面中側邊欄的屬性
README.md示例

# 主界面簡介
------
此文檔的簡單描述

### 目錄介紹
* [目錄1](1.md)
* [目錄2](2.md)
* [目錄3](2.md)
* [目錄4](4.md)
複製代碼

SUMMARY.md示例

* [目錄1](1.md)
* [目錄2](2.md)
* [目錄3](2.md)
* [目錄4](4.md)
複製代碼

項目根目錄下能夠建立 book.json 實現全局配置文件信息

{
    "title": "MedusaSorcerer的博客文檔",
    "author": "MedusaSorcerer",
    "description": "MedusaSorcerer的博客文檔",
    "language": "zh-hans",
    "gitbook": "3.0.0",
    "structure": {
        "readme": "README.md"
    },
    "plugins": [
        "-highlight",
        "-github",
        "-search",
        "-lunr",
        "livereload",
        "back-to-top-button",
        "code",
        "prism",
        "copy-code-button",
        "search-pro",
        "splitter",
        "-sharing-plus",
        "tbfed-pagefooter",
        "click-reveal"
    ],
    "pluginsConfig": {
        "tbfed-pagefooter": {
            "modify_label": "該文件修訂時間：",
            "modify_format": "YYYY-MM-DD HH:mm:ss"
        }
    },
    "links": {
        "sidebar": {
            "博客主頁": "https://juejin.im/user/5da32395e51d4578200cc9c5/posts"
        },
        "sharing": {
            "google": false,
            "facebook": false,
            "twitter": false,
            "weibo": false,
            "all": false
        }
    }
}
複製代碼

關鍵字	描述	示例
title	項目標題	MedusaSorcerer的博客文檔
author	項目做者	MedusaSorcerer
description	項目描述信息	-
language	項目語言	查看下錶
gitbook	Gitbook版本信息	3.0.0
structure	結構信息	{"readme": "README.md"} 指定readme的文件
plugins	須要安裝或者禁用的插件名稱	-
pluginsConfig	安裝的插件須要自定義的配置	-
links.sidebar	文檔添加其餘連接地址	{"博客主頁": "juejin.im/user/5da323…"} {名稱:地址}
links.sharing	對文檔的圖標連接是否啓用的配置	-

支持的語言列表, 版本之間存在差別, 僅供參考

語言簡寫	描述	語言簡寫	描述
en	英語	ar	阿拉伯語
bn	馬來語	cs	捷克語
de	德語	es	西班牙語
fa	波斯語	fi	芬蘭語
fr	法語	he	希伯來語
it	意大利語	ja	日語
ko	韓語	no	挪威語
pl	波蘭語	pt	葡萄牙語
ro	羅馬尼亞語	ru	俄語
sv	瑞典語	uk	烏克蘭語
vi	越南語	-	-
zh-hans	簡體漢語	zh-tw	繁體漢語

Gitbook插件介紹

安裝的插件使用 "插件名" 註冊在 plugins 裏面便可, 禁用的插件使用 "-插件名"註冊在 plugins 裏面便可
默認啓用的插件 highlight search sharing font-settings livereload

插件名稱	描述	舉個栗子
highlight	代碼高亮	-
search	導航欄英文檢索功能	-
font-settings	字體設置	-
livereload	爲GitBook實時從新加載	-
disqus	添加disqus評論	"plugins": [     "disqus" ], "pluginsConfig": {     "disqus": {         "shortName": "gitbookuse"     } }
search-pro	支持中文搜索, 須要將 默認的search插件去掉	"plugins": [     "-search",     "search-pro" ], "pluginsConfig": {     "search-pro": {         "cutWordLib": "nodejieba",         "defineWord" : ["Gitbook Use"]     } }
advanced-emoji	支持emoji表情	"plugins": [     "advanced-emoji" ]
github	添加github圖標	"plugins": [      "github"  ], "pluginsConfig": {     "github": {         "url": "juejin.im/user/5da323…"     } }
ace	使gitbook支持ace	"plugins": [     "ace" ]
emphasize	爲文字加上底色	"plugins": [     "emphasize" ]
katex	支持數學公式	"plugins": [     "katex" ]
include-codeblock	使用代碼塊的格式顯 示所包含文件的內容	"plugins": [     "include-codeblock" ]
mermaid	支持渲染Mermaid圖表	"plugins": [     "mermaid" ]
splitter	使側邊欄寬度可自由調節	"plugins": [     "splitter" ]
sharing	分享當前頁面, 默認插件	"plugins": [     "-sharing" ] "pluginsConfig": {     "sharing": {         "weibo": true,         "facebook": true,         "twitter": true,         "google": false,         "instapaper": false,         "vk": false,         "all": [             "facebook", "google", "twitter",                 "weibo", "instapaper"         ]     } }
tbfed-pagefooter	爲頁面添加頁腳	"plugins": [    "tbfed-pagefooter" ], "pluginsConfig": {     "tbfed-pagefooter": {         "copyright":"Copyright &copy zhangjikai.com 2015",         "modify_label": "該文件修訂時間：",         "modify_format": "YYYY-MM-DD HH:mm:ss"     } }
toggle-chapters	使左側的章節目錄能夠摺疊	"plugins": [     "toggle-chapters" ]
sectionx	將頁面分塊顯示	"plugins": [     "sectionx" ]
codeblock-filename	爲代碼塊添加文件名稱	"plugins": [     "codeblock-filename" ]
ga	google 統計	"plugins": [     "ga"  ], "pluginsConfig": {     "ga": {         "token": "UA-XXXX-Y"     } }
baidu	百度統計	"plugin": [     "baidu"  ], "pluginsConfig": {     "baidu": {         "token": "YOUR TOKEN"     } }

Gitbook錯誤處理

1. 執行 npm install gitbook-cli -g 的時候下載失敗

   進入你的 Users\當前用戶\AppData\Roaming\npm\node_modules 目錄下
   查看是否有 gitbook-cli 目錄
   
   若是目錄存在, 刪除 gitbook-cli 目錄
   若是目錄不存在, 使用 npm 卸載 Gitbook 遺留文件
   再從新執行下載便可成功
   複製代碼

2. 修改項目文件保存後, gitbook serve 不支持熱加載
   當你修改 Gitbook 項目保存後, serve 重啓的時提示沒法使用 mkdir 操做, 以致於不能達到重啓的目的
   那麼你須要進行如下操做:

   • 找到你下載的gitbook版本文件夾: 通常位於Users\當前用戶\.gitbook\versions\下會有對應版本號的文件夾名稱
   • 在對應版本文件夾內找到lib\cli\serve.js文件
   • 複製如下代碼放置serve.js文件中

     /* 代碼首行 */
     const fs=require("fs");
     
     /* 任意空白位置 */
     function deleteFolder(path) {
     let files = [];
     if( fs.existsSync(path) ) {
         files = fs.readdirSync(path);
         files.forEach(function(file,index){
             let curPath = path + "/" + file;
             if(fs.statSync(curPath).isDirectory()) {
                 deleteFolder(curPath);
             } else {
                 fs.unlinkSync(curPath);
             }
         });
         fs.rmdirSync(path);
         }
     }
     複製代碼

   • 在serve.js找到函數體generateBook
   • 在函數內var outputFolder = getOutputFolder(args);後另起一行寫入如下代碼

     if (server.isRunning()) deleteFolder(outputFolder)
     複製代碼

   • 保存退出, 重啓gitbook, 發現熱加載生效了

   注意: 當你中止服務的時候, 若服務沒有自動刪除 _book 文件夾時, 你須要手動刪除 _book 文件夾 ``

3. 安裝 Gitbook 後沒有找到 gitbook 指令

   須要在你的環境變臉中添加 Gitbook 的變量 Path
   Users\當前用戶\AppData\Roaming\npm
   複製代碼