Gitbook 快速入門
1. 介紹
Gitbook 是一款優(yōu)秀的 基于 Node.js 的開源文檔管理工具，具有豐富的開源插件。
GitBook 支持 Markdown 和 AsciiDoc 兩種語法格式，能夠輸出 html，pdf，epub，mobi 等多種格式。
2. 條件
nodejs 安裝 node一定要安裝10.X版本，否則報如下錯誤：
CLI version: 2.3.2
Installing GitBook 3.2.3
/usr/local/node/lib/node_modules/gitbook-cli/node_modules/npm/node_modules/graceful-fs/polyfills.js:287
if (cb) cb.apply(this, arguments)
^
TypeError: cb.apply is not a function
at /usr/local/node/lib/node_modules/gitbook-cli/node_modules/npm/node_modules/graceful-fs/polyfills.js:287:18
at FSReqCallback.oncomplete (fs.js:193:5)
系統(tǒng)：ubuntu：18.04
3. gitbook 安裝
$ npm install gitbook-cli -g
/usr/local/node/bin/gitbook -> /usr/local/node/lib/node_modules/gitbook-cli/bin/gitbook.js
+ gitbook-cli@2.3.2
added 578 packages from 672 contributors in 191.662s
#找到gitbook命令位置
$ ls /usr/local/node-v10.24.0-linux-x64/bin/
gitbook node node_modules/ npm npx package-lock.json
#添加軟連接
$ ln -s /usr/local/node-v10.24.0-linux-x64/bin/gitbook /usr/local/bin/
$ ln -s /usr/local/node-v10.24.0-linux-x64/bin/book /usr/local/bin/
$ gitbook -V
CLI version: 2.3.2
Installing GitBook 3.2.3
gitbook@3.2.3 ../../../../tmp/tmp-117466TKiRhUq3ov0O/node_modules/gitbook
├── escape-html@1.0.3
├── escape-string-regexp@1.0.5
├── destroy@1.0.4
├── ignore@3.1.2
├── bash-color@0.0.4
├── gitbook-plugin-livereload@0.0.1
├── cp@0.2.0
├── nunjucks-do@1.0.0
├── graceful-fs@4.1.4
├── github-slugid@1.0.1
├── direction@0.1.5
├── q@1.4.1
├── spawn-cmd@0.0.2
├── gitbook-plugin-fontsettings@2.0.0
├── open@0.0.5
├── is@3.3.0
├── object-path@0.9.2
├── extend@3.0.2
├── json-schema-defaults@0.1.1
├── gitbook-plugin-search@2.2.1
├── jsonschema@1.1.0
├── crc@3.4.0
├── urijs@1.18.0
├── semver@5.1.0
├── immutable@3.8.2
├── front-matter@2.3.0
├── npmi@2.0.1 (semver@4.3.6)
├── resolve@1.1.7
├── gitbook-plugin-theme-default@1.0.7
├── moment@2.13.0
├── npm@3.9.2
├── dom-serializer@0.1.0 (domelementtype@1.1.3, entities@1.1.2)
├── tmp@0.0.28 (os-tmpdir@1.0.2)
├── error@7.0.2 (xtend@4.0.2, string-template@0.2.1)
├── omit-keys@0.1.0 (isobject@0.2.0, array-difference@0.0.1)
├── mkdirp@0.5.1 (minimist@0.0.8)
├── js-yaml@3.14.1 (esprima@4.0.1, argparse@1.0.10)
├── gitbook-plugin-lunr@1.2.0 (html-entities@1.2.0, lunr@0.5.12)
├── gitbook-plugin-highlight@2.0.2 (highlight.js@9.2.0)
├── gitbook-plugin-sharing@1.0.2 (lodash@3.10.1)
├── i18n-t@1.0.1 (lodash@4.17.21)
├── gitbook-markdown@1.3.2 (kramed-text-renderer@0.2.1, gitbook-html@1.3.3, kramed@0.5.6, lodash@4.17.21)
├── gitbook-asciidoc@1.2.2 (gitbook-html@1.3.3, asciidoctor.js@1.5.5-1, lodash@4.17.21)
├── send@0.13.2 (fresh@0.3.0, etag@1.7.0, statuses@1.2.1, range-parser@1.0.3, ms@0.7.1, depd@1.1.2, mime@1.3.4, debug@2.2.0, http-errors@1.3.1, on-finished@2.3.0)
├── fresh-require@1.0.3 (is-require@0.0.1, shallow-copy@0.0.1, astw@1.3.0, acorn@0.9.0, sleuth@0.1.1, escodegen@1.14.3, through2@0.6.5)
├── rmdir@1.2.0 (node.flow@1.2.3)
├── request@2.72.0 (tunnel-agent@0.4.3, aws-sign2@0.6.0, forever-agent@0.6.1, oauth-sign@0.8.2, is-typedarray@1.0.0, caseless@0.11.0, stringstream@0.0.6, aws4@1.11.0, isstream@0.1.2, json-stringify-safe@5.0.1, tough-cookie@2.2.2, node-uuid@1.4.8, qs@6.1.2, hawk@3.1.3, combined-stream@1.0.8, mime-types@2.1.34, http-signature@1.1.1, form-data@1.0.1, bl@1.1.2, har-validator@2.0.6)
├── read-installed@4.0.3 (debuglog@1.0.1, util-extend@1.0.3, slide@1.1.6, readdir-scoped-modules@1.1.0, read-package-json@2.1.2)
├── cpr@1.1.1 (rimraf@2.4.5)
├── tiny-lr@0.2.1 (parseurl@1.3.3, livereload-js@2.4.0, qs@5.1.0, debug@2.2.0, faye-websocket@0.10.0, body-parser@1.14.2)
├── cheerio@0.20.0 (entities@1.1.2, lodash@4.17.21, css-select@1.2.0, htmlparser2@3.8.3, jsdom@7.2.2)
├── juice@2.0.0 (deep-extend@0.4.2, slick@1.12.2, batch@0.5.3, cssom@0.3.1, cross-spawn-async@2.2.5, commander@2.9.0, web-resource-inliner@2.0.0)
├── chokidar@1.5.0 (async-each@1.0.3, path-is-absolute@1.0.1, inherits@2.0.4, glob-parent@2.0.0, is-glob@2.0.1, is-binary-path@1.0.1, anymatch@1.3.2, readdirp@2.2.1)
└── nunjucks@2.5.2 (asap@2.0.6, yargs@3.32.0, chokidar@1.7.0)
GitBook version: 3.2.3
4. gitbook 創(chuàng)建
$ mkdir gitbook-demo
$ cd gitbook-demo
#使用 gitbook init 初始化書籍目錄
$ gitbook init
warn: no summary file in this book
info: create README.md
info: create SUMMARY.md
info: initialization is finished
$ ls
README.md SUMMARY.md
#使用 gitbook build 編譯書籍
$ gitbook build
info: 7 plugins are installed
info: 6 explicitly listed
info: loading plugin "highlight"... OK
info: loading plugin "search"... OK
info: loading plugin "lunr"... OK
info: loading plugin "sharing"... OK
info: loading plugin "fontsettings"... OK
info: loading plugin "theme-default"... OK
info: found 1 pages
info: found 0 asset files
info: >> generation finished with success in 0.4s !
$ ls
_book README.md SUMMARY.md
$ ls _book/
gitbook index.html search_index.json
$ ls _book/gitbook/
fonts gitbook.js gitbook-plugin-fontsettings gitbook-plugin-highlight gitbook-plugin-lunr gitbook-plugin-search gitbook-plugin-sharing images style.css theme.js
#使用 gitbook serve 編譯并預(yù)覽書籍
$ gitbook serve
Live reload server started on port: 35729
Press CTRL+C to quit ...
info: 7 plugins are installed
info: loading plugin "livereload"... OK
info: loading plugin "highlight"... OK
info: loading plugin "search"... OK
info: loading plugin "lunr"... OK
info: loading plugin "sharing"... OK
info: loading plugin "fontsettings"... OK
info: loading plugin "theme-default"... OK
info: found 1 pages
info: found 0 asset files
info: >> generation finished with success in 0.5s !
Starting server ...
Serving book on http://localhost:4000
效果
圖中側(cè)欄Introduction的內(nèi)容正是README.md的內(nèi)容，SUMMARY.md 是編寫界面?zhèn)葯诘哪夸浗Y(jié)構(gòu)。
$ cat README.md
# Introduction
$ cat SUMMARY.md
# Summary
* [Introduction](README.md)
5. SUMMARY.md
GitBook 使用文件 SUMMARY.md 來定義書本的章節(jié)和子章節(jié)的結(jié)構(gòu)。文件 SUMMARY.md 被用來生成書本內(nèi)容的預(yù)覽表。SUMMARY.md 的格式是一個簡單的鏈接列表，鏈接的名字是章節(jié)的名字，鏈接的指向是章節(jié)文件的路徑。子章節(jié)被簡單的定義為一個內(nèi)嵌于父章節(jié)的列表。以 # 開頭的行為注釋被忽略。
GitBook使用一個SUMMARY.md文件來定義文檔的菜單。
雖說在官方文檔中，它是可選的，但是它相當重要，控制了左邊菜單欄的顯示內(nèi)容。它通過 Markdown 中的列表語法來表示文件的父子關(guān)系。緊湊型的。
創(chuàng)建一個目錄，并編寫一個markdown格式的文檔
$ mkdir git
$ mv git_training.md git
$ ls
_book book.json book.json_bak git kubernetes node_modules README.md SUMMARY.md
$ ls git/
1_git_introduce.md 2_git_command.md
編寫SUMMARY.md
# Summary
## 前言
* [Introduction](README.md)
## git
* [git 介紹](git/1_git_introduce.md)
* [git 命令](git/2_git_training.md)
啟動
$ gitbook serve
效果：
當 md 文件數(shù)量非常多時，我們可以利用 插件 summary 自動生成菜單 summary 文件的介紹。
6. README.md
書本的首頁內(nèi)容默認是從文件 README.md 中提取的。
README.md是 gitbook 最基礎(chǔ)的文件之一，它一般用來描述這本書最基本的信息。 它呈現(xiàn)給讀者這本書最初的樣子，如果內(nèi)容不夠簡潔明了，很可能就沒有看下去的欲望了。
可以通過 gitbook init 自動創(chuàng)建該文件。
如果這個文件名沒有出現(xiàn)在 SUMMARY.md (目錄索引文件) 中，那么它會被添加為章節(jié)的第一個條目。
如何替代README.md
一些項目更愿意將 README.md 文件作為項目的介紹而不是書的介紹。
大部分代碼托管平臺將 README.md 自動顯示到項目首頁，如果你不喜歡這樣。 從GitBook >2.0.0 起，就可以在 book.json 中定義某個文件作為README。
刪除掉SUMMARY.md文檔關(guān)于README.md的引用
編寫information.md
$ cat information.md
---
這是一本關(guān)于介紹git、github、gitlab、gitbook的書籍。
比起官方的理解，它更接近體驗訓(xùn)練。
book.json添加structure參數(shù)
book.json
{
"structure" : {
"readme" : "information.md"
}
}
啟動
$ gitbook serve
效果：默認的首頁
7. book.json
7.1 側(cè)欄添加鏈接
$ ls
_book book.json kubernetes README.md SUMMARY.md
$ vim book.json
{
"author": "zongxun <me@zongxun.cn>",
"description": "This is a sample book created by gitbook",
"extension": null,
"generator": "site",
"links": {
"sharing": {
"all": null,
"facebook": null,
"google": null,
"twitter": null,
"weibo": null
},
"sidebar": {
"Blog": "https://blog.csdn.net/xixihahalelehehe?spm=1000.2115.3001.5343"
}
},
"output": null,
"pdf": {
"fontSize": 12,
"footerTemplate": null,
"headerTemplate": null,
"margin": {
"bottom": 36,
"left": 62,
"right": 62,
"top": 36
},
"pageNumbers": false,
"paperSize": "a4"
},
"plugins": [],
"title": "GitBook Handbook",
"variables": {}
}
$ gitbook serve
Live reload server started on port: 35729
Press CTRL+C to quit ...
info: 7 plugins are installed
info: loading plugin "livereload"... OK
info: loading plugin "highlight"... OK
info: loading plugin "search"... OK
info: loading plugin "lunr"... OK
info: loading plugin "sharing"... OK
info: loading plugin "fontsettings"... OK
info: loading plugin "theme-default"... OK
info: found 1 pages
info: found 0 asset files
info: >> generation finished with success in 0.5s !
Starting server ...
Serving book on http://localhost:4000
效果，只看到了一個Blog鏈接。
7.2 添加一個插件
編寫book.json添加新theme-comscore顏色插件
$ cat book.json
{
"author": "zongxun <me@zongxun.cn>",
"description": "This is a sample book created by gitbook",
"extension": null,
"generator": "site",
"links": {
"sharing": {
"all": null,
"facebook": null,
"google": null,
"twitter": null,
"weibo": null
},
"sidebar": {
"Blog": "https://blog.csdn.net/xixihahalelehehe?spm=1000.2115.3001.5343"
}
},
"output": null,
"pdf": {
"fontSize": 12,
"footerTemplate": null,
"headerTemplate": null,
"margin": {
"bottom": 36,
"left": 62,
"right": 62,
"top": 36
},
"pageNumbers": false,
"paperSize": "a4"
},
"plugins": [
"theme-comscore"
],
"title": "GitBook Handbook",
"variables": {}
}
安裝插件
gitbook install
info: installing 1 plugins using npm@3.9.2
info:
info: installing plugin "theme-comscore"
info: install plugin "theme-comscore" (*) from NPM with version 0.0.3
/root/github/gitbook-demo
└── gitbook-plugin-theme-comscore@0.0.3
info: >> plugin "theme-comscore" installed with success
執(zhí)行文章來源：http://www.zghlxwxcb.cn/news/detail-468905.html
$ gitbook serve
添加主題插件前：
添加主題插件后：
文章來源地址http://www.zghlxwxcb.cn/news/detail-468905.html
到了這里，關(guān)于gitbook 快速入門的文章就介紹完了。如果您還想了解更多內(nèi)容，請在右上角搜索TOY模板網(wǎng)以前的文章或繼續(xù)瀏覽下面的相關(guān)文章，希望大家以后多多支持TOY模板網(wǎng)！
