基于 Gitbook 的開源生態，更具美觀的項目文檔設計

項目源碼地址：https://github.com/jiyiren/ProjectDoc

有色Demo預覽地址：https://jiyiren.github.io/project-doc/

無色Demo預覽地址：https://jiyiren.github.io/project-doc-plain/

無色樣式：

基本環境

安裝 Nodejs

• 全球官網：https://nodejs.org/en
• 中文官網：http://nodejs.cn/

下載安裝后測試下 Node 是否安裝成功：

1
2

$ node -v
v10.15.3

如果提示命令沒找到，那么是由于 Node 沒有加入環境變量，大家將安裝的 Node 環境地址放在環境變量里就可以了。

安裝 gitbook

直接輸入命令進行安裝：

1

$ npm install gitbook-cli -g

npm 也是和 node 一起安裝的，node 存在 npm 就存在。-g 參數表示全局安裝，也就是模塊包會安裝到全局環境里，這個是推薦做法，因為像這種工具命令全局安裝是最好的。而項目依賴模塊則項目內安裝即可。

測試 gitbook 命令是否安裝成功：

1
2
3

$ gitbook -V
CLI version: 2.3.2
GitBook version: 3.2.3

使用 gitbook

任意找一個空目錄，執行：

1
2
3
4
5

$ gitbook init
warn: no summary file in this book 
info: create README.md 
info: create SUMMARY.md 
info: initialization is finished

會在當前目錄下創建出兩個文件，分別是：

1
2

README.md
SUMMARY.md

暫且先不管其他的，我們現在可以直接運行試試，先把流程走通：

1
2

$ gitbook build
$ gitbook serve

上面的 gitbook build 是編譯整個 markdown 文件，然后在當前目錄生成 _book 目錄，里面是 html 頁面。這個主要在部署的時候用到。

而 gitbook serve 是本地調試開啟服務命令，項目最終是要成網站的，因此, 該命令可以開啟本地 http://127.0.0.1:4000 地址作為網站瀏覽地址。

假如大家執行 gitbook serve 出錯，建議大家先 gitbook build 在 gitbook serve.

項目結構

基本結構

我們上面通過 gitbook init 生成的只有下面兩個文件：

1
2

README.md
SUMMARY.md

但實際上我們要定制我們的 gitbook 項目，項目還有一個配置文件的: book.json，只不過 gitbook init 沒有自動創建出來。我們一看這文件名就應該知道這個配置文件就是 json 格式的。最基本的 book.json 長什么樣子呢？如下所示：

1
2
3
4
5
6
7
8
9
10
11
12
13
14

{
  "title": "ProjectDoc",
  "author": "jiyiren",
  "description": "ProjectDoc",
  "language": "zh-hans",
  "links": {
  },
  "styles": {
  },
  "plugins": [
  ],
  "pluginsConfig": {
  }
}

基本 book.json 內容：

• title: 網站標題;
• author: 網站作者;
• description: 網站描述;
• language: 網站語言;
• links: 側邊欄配置項;
• styles: 全局自定義網站樣式;
• plugins: 插件配置項;
• pluginsConfig: 配置插件的配置項，為一些插件傳入參數的;

簡單示例

上面最基本的 book.json，對默認界面基本無變動，其界面顯示為：

我們來一個簡單 gitbook 定制，book.json 如下：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

{
	"title": "ProjectDoc",
	"author": "jiyiren",
	"description": "ProjectDoc",
	"language": "zh-hans",
	"links": {
	  "sidebar": {
	    "本文托管": "https://github.com/jiyiren/ProjectDoc"
	  }
	},
	"styles": {
	},
	"plugins": [
	    "anchor-navigation-ex@0.1.8"
	],
	"pluginsConfig": {
	    "anchor-navigation-ex": {
	        "isRewritePageTitle": true,
	        "isShowTocTitleIcon": true,
	        "tocLevel1Icon": "fa fa-hand-o-right",
	        "tocLevel2Icon": "fa fa-hand-o-right",
	        "tocLevel3Icon": "fa fa-hand-o-right"
	    }
	}
}

其界面為如下，多出左側欄 本文托管，和文章右側的 目錄以及回到開頭 按鈕。

必備插件

插件使用

• 插件添加：插件的使用就放在 book.json 的 plugins 和 pluginsConfig 鍵中，形式如：pluginName@versionName 也就是插件名@版本，當然沒有版本時，采用最新默認版本。
• 插件刪除：要刪除自帶的插件則使用 -pluginName 即 -插件名

下面介紹本文檔使用到的插件。

splitter

使側邊欄的寬度可以自由調節

1
2
3

"plugins": [
    "splitter"
]

simple-page-toc

文章頁面右上角顯示目錄，這個目前已經被廢棄，建議每個頁面自己生成 md 目錄。

1
2
3
4
5
6
7
8
9
10
11

{
    "plugins" : [
        "simple-page-toc"
    ],
    "pluginsConfig": {
        "simple-page-toc": {
            "maxDepth": 3,
            "skipFirstH1": true
        }
    }
}

search-plus

支持中文搜索, 需要將默認的 search 和 lunr 插件去掉

1
2
3

{
    "plugins": ["-lunr", "-search", "search-plus"]
}

tbfed-pagefooter

為頁面添加頁腳

1
2
3
4
5
6
7
8
9
10

"plugins": [
   "tbfed-pagefooter"
],
"pluginsConfig": {
    "tbfed-pagefooter": {
        "copyright":"Copyright ? zhangjikai.com 2017",
        "modify_label": "該文件修訂時間：",
        "modify_format": "YYYY-MM-DD HH:mm:ss"
    }
}

anchor-navigation-ex

添加Toc到側邊懸浮導航以及回到頂部按鈕，這個自動生成的懸浮目錄必須以下面形式書寫，也就是一定要有一個是 h1 開頭的，否則不能識別。

1
2
3

# h1
## h2
### h3

配置代碼：

1
2
3
4
5
6
7
8
9
10
11
12
13
14

{
    "plugins": [
        "anchor-navigation-ex"
    ],
    "pluginsConfig": {
        "anchor-navigation-ex": {
            "isRewritePageTitle": true,
            "isShowTocTitleIcon": true,
            "tocLevel1Icon": "fa fa-hand-o-right",
            "tocLevel2Icon": "fa fa-hand-o-right",
            "tocLevel3Icon": "fa fa-hand-o-right"
        }
    }
}

prism

使用 Prism.js 為語法添加高亮顯示，需要將 highlight 插件去掉。該插件自帶的主題樣式較少，可以再安裝 prism-themes 插件，里面多提供了幾種樣式，具體的樣式可以參考 這里，在設置樣式時要注意設置 css 文件名，而不是樣式名。

1
2
3
4
5
6
7
8
9
10
11
12
13
14

{
"plugins": [
    "-highlight",
    "prism@^2.1.0",
    "prism-themes@^0.0.2"
  ],
"pluginsConfig": {
	"prism": {
      "css": [
        "prism-themes/themes/prism-a11y-dark.css"
      ]
    }
  }
}

其他插件大家可以參考這個博主的：http://gitbook.zhangjikai.com/plugins.html

最終的頁面示例

有配色見：https://jiyiren.github.io/project-doc/

無配色見：https://jiyiren.github.io/project-doc-plain/

參考

1. https://redis.io/
2. https://jiyiren.github.io/2018/08/04/kafka/
3. http://gitbook.zhangjikai.com/themes.html
4. http://www.chengweiyang.cn/gitbook/
5. https://www.cnblogs.com/YangJieCheng/p/7991660.html

一、18個搜索網站

1.鳩摩搜索

2.盤搜

3.西林街搜索

4.胖次搜索

5.diaosi搜

6.盤多多搜索

7.哎喲喂啊網盤搜索

8.去轉盤網

9.麥庫搜索

10. sov5搜索

11.11網盤搜搜

12.網盤007

13.VeryPan

14.盤搜搜

15.史萊姆搜索

16.云搜

17.特百度

18.百度網盤之家

二、40個電子書下載網站

1.威鋒網論壇

2. Vol.moe漫畫資源

3.好讀（網站）

4. Readfree（網站）

5.so-kindle

6.azw3吧

7.繽鬧 Kindle 論壇

8.Hi-PDA（論壇）

9.書伴（網站）

10.西東網

11.世界數字圖書館

12.學習資料庫

13.敏學網

14.學兔兔

15.若藍格

16. PDF之家

17.易讀kindle

18.書荒部落

19.iDesk

20.周讀

21愛下電子書

22.北半球

23.知軒藏書（精校）

24.我愛讀電子書

25.我要讀PDF

26.掌上書苑

27.阡陌小筑

28.青年文摘

29.飛庫網

30.百度文庫

31.百度網盤

32.新浪微盤

33.愛問共享資料

34.逛電驢

35. SF輕小說

36.久久小說下載網

37.愛奇電子書

38.書格（古籍可下載）

39.書快

40.我是TXT電子書

17個書籍在線閱讀網站

1.紅袖添香

2.小說閱讀網

3.起點中文網

4.瀟湘書院

5.逐浪文學

6.鐵血書庫

7.幻劍書盟

8.悠讀文學

9.木木文摘

10.17K小說網

11.努努書坊

12.追書神器

13. 99藏書網

14.東里書齋（古籍）

15.漢川草廬（古籍）

16.學術前沿在線

17.在線讀書

15個外文書籍網站

1. Project Gutenberg：（英文書籍）

2. manybooks（外文書籍）

3. Free-Ebooks（外文書籍）

4. en8848（外文書籍）

5. Allitebooks.（外文書籍）

6. pdf-magazine英文雜志

7.七彩英語（外文書籍）

8.bookboon（外文書籍）

9. EpubBooks：（英文書籍）

10. BookDL：（英文書籍）

11. Gitbook（英文書籍）

12. Baen Free Library：（英文書籍）

13. hIt-ebooks（英文版）

14. Libgen（英文版）

15.國外兒童繪本大全下載網

21個網上書店

1.亞馬遜

2.當當讀書

3.京東書店

4.孔夫子舊書網

5.多看閱讀

6.中國圖書網

7. china-pub

8.文軒網

9.淘書網

10.博庫網

11.中關村圖書大廈

12.廣州購書中心

13.蔚藍網

14.金牌自考書店

15.蘇寧易購書城

16.商務印書館

17.階梯圖書網

18.希望書店

19.新東方圖書網

20.瀾瑞外文網上書店

21.百度閱讀