概述
GitBook 是使用 GitHub / Git 和 Markdown（或AsciiDoc）構(gòu)建漂亮?xí)拿钚泄ぞ撸ê蚇ode.js庫）。

GitBook 可以將您的內(nèi)容作為網(wǎng)站（可定制和可擴(kuò)展）或電子書（PDF吴藻，ePub或Mobi）輸出瑰剃。

GitBook.com 是使用 GitBook 格式創(chuàng)建和托管圖書的在線平臺眠副。它提供托管，協(xié)作功能和易于使用的編輯器。

GitBook 安裝
本地安裝
環(huán)境要求
安裝 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 來構(gòu)建一本書廷痘。

執(zhí)行下面的命令蔓涧，查看 GitBook 版本，以驗證安裝成功笋额。

$ gitbook -V
安裝歷史版本
gitbook-cli 可以輕松下載并安裝其他版本的GitBook來測試您的書籍：

$ gitbook fetch beta
使用 gitbook ls-remote 會列舉可以下載的版本元暴。

創(chuàng)建一本書
初始化
GitBook可以設(shè)置一個樣板書：

$ gitbook init
如果您希望將書籍創(chuàng)建到一個新目錄中，可以通過運行 gitbook init ./directory 這樣做兄猩。

構(gòu)建
使用下面的命令茉盏，會在項目的目錄下生成一個 _book 目錄鉴未，里面的內(nèi)容為靜態(tài)站點的資源文件：

$ gitbook build
Debugging
您可以使用選項 --log=debug 和 --debug 來獲取更好的錯誤消息（使用堆棧跟蹤）。例如：

$ gitbook build ./ --log=debug --debug
啟動服務(wù)
使用下列命令會運行一個 web 服務(wù), 通過 http://localhost:4000/ 可以預(yù)覽書籍

$ gitbook serve
GitBook 命令
這里主要介紹一下 GitBook 的命令行工具 gitbook-cli 的一些命令, 首先說明兩點:

gitbook-cli 和 gitbook 是兩個軟件
gitbook-cli 會將下載的 gitbook 的不同版本放到 ~/.gitbook中, 可以通過設(shè)置GITBOOK_DIR環(huán)境變量來指定另外的文件夾
列出 gitbook 所有的命令

gitbook help
輸出 gitbook-cli 的幫助信息

gitbook --help
生成靜態(tài)網(wǎng)頁

gitbook build
生成靜態(tài)網(wǎng)頁并運行服務(wù)器

gitbook serve
生成時指定gitbook的版本, 本地沒有會先下載

gitbook build --gitbook=2.0.1
列出本地所有的gitbook版本

gitbook ls
列出遠(yuǎn)程可用的gitbook版本

gitbook ls-remote
安裝對應(yīng)的gitbook版本

gitbook fetch 標(biāo)簽/版本號
更新到gitbook的最新版本

gitbook update
卸載對應(yīng)的gitbook版本

gitbook uninstall 2.0.1
指定log的級別

gitbook build --log=debug
輸出錯誤信息

gitbook builid --debug
Gitbook 目錄結(jié)構(gòu)
GitBook 項目結(jié)構(gòu)
GitBook使用簡單的目錄結(jié)構(gòu)鸠姨。在 SUMMARY （即 SUMMARY.md 文件）中列出的所有 Markdown / Asciidoc 文件將被轉(zhuǎn)換為 HTML歼狼。多語言書籍結(jié)構(gòu)略有不同。

一個基本的 GitBook 電子書結(jié)構(gòu)通常如下：

.
├── 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 詞匯/注釋術(shù)語列表 (optional)
靜態(tài)文件和圖片
靜態(tài)文件是在 SUMMARY.md 中未列出的文件享怀。除非被忽略，否則所有靜態(tài)文件都將復(fù)制到輸出路徑趟咆。

忽略文件和文件夾
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é)的結(jié)構(gòu)虐唠。 SUMMARY.md 文件用于生成本書的目錄搀愧。

SUMMARY.md 的格式是一個鏈接列表。鏈接的標(biāo)題將作為章節(jié)的標(biāo)題疆偿，鏈接的目標(biāo)是該章節(jié)文件的路徑咱筛。

向父章節(jié)添加嵌套列表將創(chuàng)建子章節(jié)。

簡單示例：

Summary

• Part I
  • Writing is nice
  • GitBook is nice
• Part II
  • We love feedback
  • Better tools for authors
    每章都有一個專用頁面（part#/README.md）杆故，并分為子章節(jié)迅箩。

錨點

目錄中的章節(jié)可以使用錨點指向文件的特定部分。

Summary

Part I

• Part I
  • Writing is nice
  • GitBook is nice
• Part II
  • We love feedback
  • Better tools for authors
    部分

目錄可以分為以標(biāo)題或水平線 ---- 分隔的部分：

Summary

Part I

• Writing is nice
• GitBook is nice

Part II

• We love feedback
• Better tools for authors

• Last part without title
  Parts 只是章節(jié)組处铛，沒有專用頁面饲趋，但根據(jù)主題，它將在導(dǎo)航中顯示撤蟆。

頁面
Markdown 語法

默認(rèn)情況下奕塑，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

...
頁面前言

頁面可以包含一個可選的前言寝贡。它可以用于定義頁面的描述。前面的事情必須是文件中的第一件事值依，必須采取在三虛線之間設(shè)置的有效YAML的形式圃泡。這是一個基本的例子：

description: This is a short description of my page

The content of my page

...
Glossary
允許您指定要顯示為注釋的術(shù)語及其各自的定義。根據(jù)這些術(shù)語愿险，GitBook 將自動構(gòu)建索引并突出顯示這些術(shù)語颇蜡。

GLOSSARY.md 的格式是 h2 標(biāo)題的列表价说，以及描述段落：

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ī)設(shè)置
變量 描述
root 包含所有圖書文件的根文件夾的路徑缤弦，除了 book.json
structure 指定自述文件领迈，摘要，詞匯表等的路徑碍沐，參考 Structure paragraph.
title 您的書名狸捅，默認(rèn)值是從 README 中提取出來的。在 GitBook.com 上累提，這個字段是預(yù)填的尘喝。
description 您的書籍的描述，默認(rèn)值是從 README 中提取出來的斋陪。在 GitBook.com 上朽褪，這個字段是預(yù)填的。
author 作者名无虚。在GitBook.com上缔赠，這個字段是預(yù)填的。
isbn 國際標(biāo)準(zhǔn)書號 ISBN
language 本書的語言類型 —— ISO code 骑科。默認(rèn)值是 en
direction 文本閱讀順序橡淑。可以是 rtl （從右向左）或 ltr （從左向右）咆爽，默認(rèn)值依賴于 language 的值梁棠。
gitbook 應(yīng)該使用的GitBook版本。使用 SemVer 規(guī)范斗埂，并接受類似于 “> = 3.0.0” 的條件符糊。
author

作者姓名，在GitBook.com上呛凶，這個字段是預(yù)先填寫的男娄。

例：

"author" : "victor zhang"
description

電子書的描述，默認(rèn)值是從 README 中提取出來的漾稀。在GitBook.com上模闲，這個字段是預(yù)先填寫的。

例：

"description" : "Gitbook 教程"
direction

文本的方向崭捍∈郏可以是 rtl 或 ltr，默認(rèn)值取決于語言的值殷蛇。

例：

"direction" : "ltr"
gitbook

應(yīng)該使用的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

在左側(cè)導(dǎo)航欄添加鏈接信息

例：

"links" : {
"sidebar" : {
"Home" : "https://github.com/atlantis1024/gitbook-notes"
}
}
root

包含所有圖書文件的根文件夾的路徑亮航， book.json 文件除外荸实。

例：

"root" : "./docs",
structure

指定 Readme、Summary缴淋、Glossary 和 Languages 對應(yīng)的文件名准给。

styles

自定義頁面樣式， 默認(rèn)情況下各generator對應(yīng)的css文件

例：

"styles": {
"website": "styles/website.css",
"ebook": "styles/ebook.css",
"pdf": "styles/pdf.css",
"mobi": "styles/mobi.css",
"epub": "styles/epub.css"
}
例如要使 h1重抖、h2 標(biāo)簽有下邊框圆存， 可以在 website.css 中設(shè)置

h1 , h2{
border-bottom: 1px solid #EFEAEA;
}
title

電子書的書名，默認(rèn)值是從 README 中提取出來的仇哆。在 GitBook.com 上，這個字段是預(yù)先填寫的夫植。

例：

"title" : "gitbook-notes",
plugins
插件及其配置在 book.json 中指定讹剔。有關(guān)詳細(xì)信息。

自 3.0.0 版本開始详民，GitBook 可以使用主題延欠。有關(guān)詳細(xì)信息，請參閱 the theming section 沈跨。

變量 描述
plugins 要加載的插件列表
pluginsConfig 插件的配置
添加插件
"plugins": [
"splitter"
]
添加新插件之后需要運行 gitbook install 來安裝新的插件

去除自帶插件
Gitbook 默認(rèn)帶有 5 個插件：

highlight
search
sharing
font-settings
livereload
"plugins": [
"-search"
]
structure
除了 root 屬性之外由捎，您可以指定 Readme，Summary饿凛，Glossary 和 Languages 的名稱（而不是使用默認(rèn)名稱狞玛，如README.md）。這些文件必須在項目的根目錄下（或 root 的根目錄涧窒，如果你在 book.json 中配置了 root 屬性）心肪。不接受的路徑，如：dir / MY_README.md纠吴。

變量 描述
structure.readme Readme 文件名（默認(rèn)值是 README.md ）
structure.summary Summary 文件名（默認(rèn)值是 SUMMARY.md ）
structure.glossary Glossary 文件名（默認(rèn)值是 GLOSSARY.md ）
structure.languages Languages 文件名（默認(rèn)值是 LANGS.md ）
pdf
可以使用 book.json 中的一組選項來定制PDF輸出：

Variable Description
pdf.pageNumbers 將頁碼添加到每個頁面的底部（默認(rèn)為 true）
pdf.fontSize 基本字體大杏舶啊（默認(rèn)是 12）
pdf.fontFamily 基本字體樣式（默認(rèn)是 Arial）
pdf.paperSize 頁面尺寸，選項有： 'a0', 'a1', 'a2', 'a3', 'a4', 'a5', 'a6', 'b0', 'b1', 'b2', 'b3', 'b4', 'b5', 'b6', 'legal', 'letter' （默認(rèn)值是 a4）
pdf.margin.top 上邊界（默認(rèn)值是 56）
pdf.margin.bottom 下邊界（默認(rèn)值是 56）
pdf.margin.right 右邊界（默認(rèn)值是 62）
pdf.margin.left 左邊界（默認(rèn)值是 62）
生成電子書
GitBook 可以生成一個網(wǎng)站戴已，但也可以輸出內(nèi)容作為電子書（ePub固该，Mobi，PDF）糖儡。

Generate a PDF file

$ gitbook pdf ./ ./mybook.pdf

Generate an ePub file

$ gitbook epub ./ ./mybook.epub

Generate a Mobi file

$ gitbook mobi ./ ./mybook.mobi
安裝 ebook-convert
ebook-convert 可以用來生成電子書（epub伐坏，mobi，pdf）休玩。

GNU/Linux
安裝 Calibre application.

$ sudo aptitude install calibre
在一些 GNU / Linux 發(fā)行版中著淆，節(jié)點被安裝為 nodejs劫狠，您需要手動創(chuàng)建一個符號鏈接：

$sudo ln -s /usr/bin/nodejs /usr/bin/node
OS X
下載 Calibre application。將 calibre.app 移動到應(yīng)用程序文件夾后永部，創(chuàng)建一個符號鏈接到 ebook-convert 工具：

PATH 中的任何目錄替換 /usr/bin 独泞。

封面
封面用于所有電子書格式。您可以自己提供一個苔埋，也可以使用 autocover plugin 生成一個懦砂。

要提供封面，請將 cover.jpg 文件放在書本的根目錄下组橄。添加一個 cover_small.jpg 將指定一個較小版本的封面荞膘。封面應(yīng)為 JPEG 文件。

好的封面應(yīng)該遵守以下準(zhǔn)則：

cover.jpg 的尺寸為 1800x2360 像素玉工，cover_small.jpg 為 200x262
沒有邊界
清晰可見的書名
任何重要的文字應(yīng)該在小版本中可見
Gitbook 部署
托管到 gitbook.com
GitBook.com 是使用 GitBook 格式創(chuàng)建和托管圖書的在線平臺羽资。它提供托管，協(xié)作功能和易于使用的編輯器遵班。

創(chuàng)建新書

如下圖所示屠升，根據(jù)個人需求，選擇一個模板創(chuàng)建你的電子書狭郑。

設(shè)置書的基本信息

clone 到本地

Gitbook.com 會為每本書創(chuàng)建一個 git 倉庫腹暖。

如下圖所示，拷貝 git 地址翰萨，然后 git clone 到本地脏答。

發(fā)布

在本地按照 Gitbook 規(guī)范編輯電子書，然后 git push 到 Gitbook 的遠(yuǎn)程倉庫亩鬼。

默認(rèn)訪問地址是：https://用戶名.gitbooks.io/項目名/content/

例如：我的用戶名為 atlantis1024殖告，一個電子書項目名為 test，則訪問路徑是： https://atlantis1024.gitbooks.io/test/content/

當(dāng)然雳锋，如果你有自己的域名丛肮，也可以設(shè)置 Domains 選項，來指定訪問路徑為你的域魄缚。

托管到 Github
如果你不希望使用 Gitbook 的倉庫宝与，而是想直接使用 Github 的倉庫，也是可以的冶匹。

首先习劫，你需要綁定你的 Github 賬號。最簡單的方式當(dāng)然就是登錄 Gitbook.com 時使用 Github 賬號登錄方式了嚼隘。否則诽里，你也可以在 Account Settings 中的 Github 設(shè)置選項中去進(jìn)行綁定。

綁定了 Github 賬號后飞蛹，你可以在新建電子書時谤狡，選擇從一個指定的 Github 倉庫導(dǎo)入電子書項目灸眼。參考下圖：

只要你指定的 Github 倉庫中的文檔內(nèi)容符合 Gitbook 規(guī)范，Gitbook 就會自動根據(jù)你的每次更新去構(gòu)建生成電子書網(wǎng)站墓懂。

默認(rèn)訪問地址是：

https://Github用戶名.gitbooks.io/Github 倉庫/content/
例如：我的用戶名為 atlantis1024焰宣，Github 倉庫名為 gitbook-notes，則訪問路徑是：

https://atlantis1024.gitbooks.io/gitbook-notes/content/

托管到 Github Pages
也許你以前也了解 Github 的一個功能： GitHub Pages 捕仔。它允許用戶在 GitHub 倉庫托管你的個人匕积、組織或項目的靜態(tài)頁面（自動識別 html、css榜跌、javascript）闪唆。

建立 xxx.github.io 倉庫

要使用這個特性，首先钓葫，你必須建立一個嚴(yán)格遵循以下命名要求的倉庫：Github賬號名.github.io舉例悄蕾，我的 Github 賬號為 atlantis1024，則這個倉庫應(yīng)該叫 atlantis1024.github.io础浮。通常笼吟，這個倉庫被用來作為個人或組織的博客。

建立 gh-pages 分支

完成第1步后霸旗，在任意一個 Github 倉庫中建立一個名為 gh-pages 的分支。只要 gh-pages 中的內(nèi)容符合一個靜態(tài)站點要求戚揭，就可以在如下地址中進(jìn)行訪問：https://Github用戶名.gitbooks.io/Github 倉庫 诱告。例如：我的一個 Github 倉庫名為 react-notes，則訪問路徑是：https://atlantis1024.github.io/react-notes

自動化發(fā)布到 gh-pages

如果每次都手動 git push 到遠(yuǎn)程 gh-pages 分支民晒，略有點麻煩精居。

怎么實現(xiàn)自動化發(fā)布呢？

有兩種方法：

使用 gh-pages 插件

如果你了解 Nodejs潜必，那么最簡單的發(fā)布方式就是使用 gh-pages 插件靴姿。

先在本地安裝插件

$ npm i -D gh-pages
然后，在 package.json 文件中添加腳本命令：

如下：-d 命令參數(shù)后面是要發(fā)布的靜態(tài)站點內(nèi)容的目錄

"scripts": {
"deploy": "gh-pages -d build"
},
腳本

寫一個執(zhí)行 git 命令的腳本就搞定了磁滚。

下面的腳本無論是在 bat 或 sh 腳本中都可以執(zhí)行佛吓。

cd build
git init
git checkout -b gh-pages
git add .
git commit -am "Update"
git push git@github.com:atlantis1024/gitbook-notes gh-pages --force"
資源
官方資源
Gitbook Github
Gitbook 官網(wǎng)
Gitbook Toolchain 文檔
Gitbook 幫助中心
教程資源
gitbook-use by zhangjikai
工具
Gitbook 編輯器