? ? 最近遇到一些問題跟啤，就是團隊中會有些伙伴踩得坑的收集問題或者有些較為復雜的業(yè)務需求文檔共享上成本較高，所以考慮弄一個文檔落地平臺缸浦，供大家去沉淀班巩、分享自己的問題或者感悟渣慕。諸如此類的東西有很多，參考其他組的方式，選擇使用gitbook來作為我們組的沉淀平臺\(^o^)/~下面來簡單介紹下他的搭建和使用逊桦。
簡單介紹下
GitBook 是使用 GitHub / Git 和 Markdown（或AsciiDoc）構建漂亮書籍的命令行工具（和Node.js庫）眨猎。可以將您的內(nèi)容作為網(wǎng)站（可定制和可擴展）或電子書（PDF强经，ePub或Mobi）輸出宵呛。
GitBook.com 是使用 GitBook 格式創(chuàng)建和托管圖書的在線平臺。它提供托管夕凝，協(xié)作功能和易于使用的編輯器宝穗。
GitBook 安裝
安裝 GitBook 是很簡單的。您的系統(tǒng)只需要滿足這兩個要求：
NodeJS（推薦使用v4.0.0及以上版本）
Windows码秉，Linux逮矛，Unix 或 Mac OS X
通過NPM安裝
安裝 GitBook 的最好辦法是通過 NPM。在終端提示符下转砖，只需運行以下命令即可安裝 GitBook：
?npm install gitbook-cli -g
gitbook-cli 是 GitBook 的一個命令行工具须鼎。它將自動安裝所需版本的 GitBook 來構建一本書。
執(zhí)行下面的命令府蔗，查看 GitBook 版本晋控，以驗證安裝成功。
gitbook -V
安裝歷史版本
gitbook-cli?可以輕松下載并安裝其他版本的GitBook來測試您的書籍：
gitbook fetch beta
使用 gitbook ls-remote?會列舉可以下載的版本姓赤。
如何創(chuàng)建一本書
GitBook可以設置一個樣板書：
?gitbook init
如果您希望將書籍創(chuàng)建到一個新目錄中赡译，可以通過運行 gitbook init ./directory 這樣做。
使用下面的命令不铆，會在項目的目錄下生成一個 _book 目錄蝌焚，里面的內(nèi)容為靜態(tài)站點的資源文件：
?gitbook build
Debugging
您可以使用選項?--log=debug?和?--debug?來獲取更好的錯誤消息（使用堆棧跟蹤）。例如：
gitbook build ./ --log=debug --debug
啟動服務
使用下列命令會運行一個 web 服務, 通過 http://localhost:4000/ 可以預覽書籍
gitbook serve
GitBook 命令
這里主要介紹一下 GitBook 的命令行工具 gitbook-cli 的一些命令, 首先說明兩點:
gitbook-cli 和 gitbook 是兩個軟件
gitbook-cli 會將下載的 gitbook 的不同版本放到 ~/.gitbook中, 可以通過設置GITBOOK_DIR環(huán)境變量來指定另外的文件夾
列出 gitbook 所有的命令
gitbook help
輸出 gitbook-cli 的幫助信息
gitbook --help
生成靜態(tài)網(wǎng)頁
gitbook build
生成靜態(tài)網(wǎng)頁并運行服務器
gitbook serve（此處可以配置啟動的目錄）
生成時指定gitbook的版本, 本地沒有會先下載
gitbook build --gitbook=2.0.1
列出本地所有的gitbook版本
gitbook ls
列出遠程可用的gitbook版本
gitbook ls-remote
安裝對應的gitbook版本
gitbook fetch 標簽/版本號
更新到gitbook的最新版本
gitbook update
卸載對應的gitbook版本
gitbook uninstall 2.0.1
指定log的級別
gitbook build --log=debug
輸出錯誤信息
gitbook builid --debug
Gitbook 目錄結構
GitBook 項目結構
GitBook使用簡單的目錄結構誓斥。在 SUMMARY （即 SUMMARY.md 文件）中列出的所有 Markdown / Asciidoc 文件將被轉(zhuǎn)換為 HTML只洒。多語言書籍結構略有不同。
一個基本的 GitBook 電子書結構通常如下：
.
├── book.json
├── README.md
├── SUMMARY.md
├── chapter-1/
|? ├── README.md
|? └── something.md
└── chapter-2/
? ? ├── README.md
? ? └── something.md
GitBook 特殊文件的功能：
文件 描述
book.json 配置數(shù)據(jù) (optional)
README.md 電子書的前言或簡介 (required)
SUMMARY.md 電子書目錄 (optional)
GLOSSARY.md 詞匯/注釋術語列表 (optional)
靜態(tài)文件和圖片
靜態(tài)文件是在?SUMMARY.md 中未列出的文件劳坑。除非被忽略毕谴，否則所有靜態(tài)文件都將復制到輸出路徑。
忽略文件和文件夾
GitBook將讀取?.gitignore距芬，.bookignore?和?.ignore?文件涝开，以獲取要過濾的文件和文件夾。這些文件中的格式遵循 .gitignore 的規(guī)則：
# This is a comment
# Ignore the file test.md
test.md
# Ignore everything in the directory "bin"
bin/*
項目與子目錄集成
對于軟件項目蔑穴，您可以使用子目錄（如 docs/ ）來存儲項目文檔的圖書忠寻。您可以配置根選項來指示 GitBook 可以找到該圖書文件的文件夾：
.
├── book.json
└── docs/
? ? ├── README.md
? ? └── SUMMARY.md
在 book.json?中配置以下內(nèi)容：
{
? ? "root": "./docs"
}
Summary
GitBook 使用?SUMMARY.md?文件來定義本書的章節(jié)和子章節(jié)的結構。?SUMMARY.md 文件用于生成本書的目錄存和。
SUMMARY.md?的格式是一個鏈接列表。鏈接的標題將作為章節(jié)的標題，鏈接的目標是該章節(jié)文件的路徑捐腿。
向父章節(jié)添加嵌套列表將創(chuàng)建子章節(jié)纵朋。
簡單示例：
# Summary
* [Part I](part1/README.md)
? ? * [Writing is nice](part1/writing.md)
? ? * [GitBook is nice](part1/gitbook.md)
* [Part II](part2/README.md)
? ? * [We love feedback](part2/feedback_please.md)
? ? * [Better tools for authors](part2/better_tools.md)
每章都有一個專用頁面（part#/README.md），并分為子章節(jié)茄袖。
錨點
目錄中的章節(jié)可以使用錨點指向文件的特定部分操软。
# Summary
### Part I
* [Part I](part1/README.md)
? ? * [Writing is nice](part1/README.md#writing)
? ? * [GitBook is nice](part1/README.md#gitbook)
* [Part II](part2/README.md)
? ? * [We love feedback](part2/README.md#feedback)
? ? * [Better tools for authors](part2/README.md#tools)
部分
目錄可以分為以標題或水平線 ---- 分隔的部分：
# Summary
### Part I
* [Writing is nice](part1/writing.md)
* [GitBook is nice](part1/gitbook.md)
### Part II
* [We love feedback](part2/feedback_please.md)
* [Better tools for authors](part2/better_tools.md)
----
* [Last part without title](part3/title.md)
Parts 只是章節(jié)組，沒有專用頁面宪祥，但根據(jù)主題聂薪，它將在導航中顯示。
頁面
Markdown 語法
默認情況下蝗羊，GitBook 的大多數(shù)文件都使用 Markdown 語法藏澳。 GitBook 推薦使用這種語法。所使用的語法類似于 GitHub Flavored Markdown syntax 耀找。
此外翔悠，你還可以選擇 AsciiDoc 語法。
頁面內(nèi)容示例：
# Title of the chapter
This is a great introduction.
## Section 1
Markdown will dictates _most_ of your **book's structure**
## Section 2
...
頁面前言
頁面可以包含一個可選的前言野芒。它可以用于定義頁面的描述蓄愁。前面的事情必須是文件中的第一件事，必須采取在三虛線之間設置的有效YAML的形式狞悲。這是一個基本的例子：
---
description: This is a short description of my page
---
# The content of my page
...
Glossary
允許您指定要顯示為注釋的術語及其各自的定義撮抓。根據(jù)這些術語，GitBook 將自動構建索引并突出顯示這些術語摇锋。
GLOSSARY.md?的格式是 h2 標題的列表胀滚，以及描述段落：
## Term
Definition for this term
## Another term
With it's definition, this can contain bold text
and all other kinds of inline markup ...
Gitbook 配置
GitBook 允許您使用靈活的配置自定義您的電子書。
這些選項在 book.json 文件中指定乱投。對于不熟悉 JSON 語法的作者咽笼，您可以使用 JSONlint 等工具驗證語法。
常規(guī)設置
變量 描述
root 包含所有圖書文件的根文件夾的路徑戚炫，除了?book.json
structure 指定自述文件剑刑，摘要，詞匯表等的路徑双肤，參考?Structure paragraph.
title 您的書名施掏，默認值是從 README 中提取出來的。在 GitBook.com 上茅糜，這個字段是預填的七芭。
description 您的書籍的描述，默認值是從 README 中提取出來的蔑赘。在 GitBook.com 上狸驳，這個字段是預填的预明。
author 作者名。在GitBook.com上耙箍，這個字段是預填的撰糠。
isbn 國際標準書號 ISBN
language 本書的語言類型 —— ISO code?。默認值是?en
direction 文本閱讀順序辩昆≡睦遥可以是 rtl?（從右向左）或 ltr （從左向右），默認值依賴于 language 的值汁针。
gitbook 應該使用的GitBook版本术辐。使用 SemVer 規(guī)范，并接受類似于 “> = 3.0.0” 的條件施无。
author
作者姓名辉词，在GitBook.com上，這個字段是預先填寫的帆精。
例：
"author" : "victor zhang"
description
電子書的描述较屿，默認值是從 README 中提取出來的。在GitBook.com上卓练，這個字段是預先填寫的隘蝎。
例：
"description" : "Gitbook 教程"
direction
文本的方向〗笃螅可以是 rtl 或 ltr嘱么，默認值取決于語言的值。
例：
"direction" : "ltr"
gitbook
應該使用的GitBook版本顽悼。使用SemVer規(guī)范曼振，接受類似于 >=3.0.0 的條件。
例：
"gitbook" : "3.0.0",
"gitbook" : ">=3.0.0"
language
Gitbook使用的語言, 版本2.6.4中可選的語言如下：
en, ar, bn, cs, de, en, es, fa, fi, fr, he, it, ja, ko, no, pl, pt, ro, ru, sv, uk, vi, zh-hans, zh-tw
例：
"language" : "zh-hans",
links
在左側導航欄添加鏈接信息
例：
"links" : {
? ? "sidebar" : {
? ? ? ? "Home" : "https://github.com/atlantis1024/gitbook-notes"
? ? }
}
root
包含所有圖書文件的根文件夾的路徑蔚龙， book.json 文件除外冰评。
例：
"root" : "./docs",
structure
指定 Readme、Summary木羹、Glossary 和 Languages 對應的文件名甲雅。
styles
自定義頁面樣式， 默認情況下各generator對應的css文件
例：
"styles": {
? ? "website": "styles/website.css",
? ? "ebook": "styles/ebook.css",
? ? "pdf": "styles/pdf.css",
? ? "mobi": "styles/mobi.css",
? ? "epub": "styles/epub.css"
}
例如要使 h1坑填、h2 標簽有下邊框抛人， 可以在 website.css 中設置
h1 , h2{
? ? border-bottom: 1px solid #EFEAEA;
}
title
電子書的書名，默認值是從 README 中提取出來的脐瑰。在 GitBook.com 上妖枚，這個字段是預先填寫的。
例：
"title" : "gitbook-notes",
plugins
插件及其配置在?book.json 中指定苍在。有關詳細信息绝页。
自 3.0.0 版本開始荠商，GitBook 可以使用主題。有關詳細信息抒寂，請參閱 ?the theming section?结啼。
變量 描述
plugins 要加載的插件列表
pluginsConfig 插件的配置
添加插件
"plugins": [
? ? "splitter"
]
添加新插件之后需要運行 gitbook install 來安裝新的插件
去除自帶插件
Gitbook 默認帶有 5 個插件：
highlight
search
sharing
font-settings
livereload
想要去除他們可以這樣
"plugins": [
? ? "-search"
]
更多具體的細節(jié)掠剑，可以參考這篇文章：使用 Gitbook 打造你的電子書
就寫到這屈芜，不多說啦，搬磚去咯(￣▽￣)／
