本文詳細講解了 Gitbook 生成電子書的完整過程，内容包括：安裝、指令、配置、文檔結構、生成電子書、部署。
限于篇幅，本文不介紹任何 Gitbook 定制化頁面的内容。
想看看 Gitbook 線上電子書效果，請猛戳這裡：
gitbook-notes
概述
GitBook 是使用 GitHub / Git 和 Markdown（或AsciiDoc）建構漂亮書籍的指令行工具（和Node.js庫）。
GitBook 可以将您的内容作為網站（可定制和可擴充）或電子書（PDF，ePub或Mobi）輸出。
GitBook.com是使用 GitBook 格式建立和托管圖書的線上平台。它提供托管，協作功能和易于使用的編輯器。
GitBook 安裝
本地安裝
環境要求
安裝 GitBook 是很簡單的。您的系統隻需要滿足這兩個要求：
- NodeJS（推薦使用v4.0.0及以上版本）
- Windows，Linux，Unix 或 Mac OS X
通過NPM安裝
安裝 GitBook 的最好辦法是通過 NPM。在終端提示符下，隻需運作以下指令即可安裝 GitBook：
$ npm install gitbook-cli -g gitbook-cli
是 GitBook 的一個指令行工具。它将自動安裝所需版本的 GitBook 來建構一本書。
執行下面的指令，檢視 GitBook 版本，以驗證安裝成功。
$ gitbook -V 安裝曆史版本
gitbook-cli
可以輕松下載下傳并安裝其他版本的GitBook來測試您的書籍：
$ gitbook fetch beta 使用
gitbook ls-remote
會列舉可以下載下傳的版本。
建立一本書
初始化
GitBook可以設定一個樣闆書：
$ gitbook init 如果您希望将書籍建立到一個新目錄中，可以通過運作
gitbook init ./directory
這樣做。
建構
使用下面的指令，會在項目的目錄下生成一個
_book
目錄，裡面的内容為靜态站點的資源檔案：
$ 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_DIR
列出 gitbook 所有的指令
gitbook help 輸出
gitbook-cli
的幫助資訊
gitbook --help 生成靜态網頁
gitbook build 生成靜态網頁并運作伺服器
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 檔案将被轉換為 HTML。多語言書籍結構略有不同。
一個基本的 GitBook 電子書結構通常如下：
.
├── book.json
├── README.md
├── SUMMARY.md
├── chapter-1/
| ├── README.md
| └── something.md
└── chapter-2/
├── README.md
└── something.md GitBook 特殊檔案的功能：
| 檔案 | 描述 |
|---|---|
| 配置資料 (optional) |
| 電子書的前言或簡介 (required) |
| 電子書目錄 (optional) |
| 詞彙/注釋術語清單 (optional) |
靜态檔案和圖檔
靜态檔案是在
SUMMARY.md
中未列出的檔案。除非被忽略，否則所有靜态檔案都将複制到輸出路徑。
忽略檔案和檔案夾
GitBook将讀取
.gitignore
，
.bookignore
.ignore
檔案，以擷取要過濾的檔案和檔案夾。這些檔案中的格式遵循
.gitignore
的規則：
# 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
中配置以下内容：
{
"root": "./docs"
} Summary
GitBook 使用
SUMMARY.md
檔案來定義本書的章節和子章節的結構。
SUMMARY.md
檔案用于生成本書的目錄。
SUMMARY.md
的格式是一個連結清單。連結的标題将作為章節的标題，連結的目标是該章節檔案的路徑。
向父章節添加嵌套清單将建立子章節。
簡單示例：
# 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
），并分為子章節。
錨點
目錄中的章節可以使用錨點指向檔案的特定部分。
# 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 隻是章節組，沒有專用頁面，但根據主題，它将在導航中顯示。
頁面
Markdown 文法
預設情況下，GitBook 的大多數檔案都使用 Markdown 文法。 GitBook 推薦使用這種文法。所使用的文法類似于
GitHub Flavored Markdown syntax。
此外，你還可以選擇
AsciiDoc 文法頁面内容示例：
# 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
允許您指定要顯示為注釋的術語及其各自的定義。根據這些術語，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 允許您使用靈活的配置自定義您的電子書。
這些選項在
檔案中指定。對于不熟悉 JSON 文法的作者，您可以使用 JSONlint 等工具驗證文法。book.json
正常設定
| 變量 | |
|---|---|
| 包含所有圖書檔案的根檔案夾的路徑，除了 |
| 指定自述檔案，摘要，詞彙表等的路徑，參考 Structure paragraph . |
| 您的書名，預設值是從 README 中提取出來的。在 GitBook.com 上，這個字段是預填的。 |
| 您的書籍的描述，預設值是從 README 中提取出來的。在 GitBook.com 上，這個字段是預填的。 |
| 作者名。在GitBook.com上，這個字段是預填的。 |
| 國際标準書号 ISBN |
| 本書的語言類型 —— ISO code 。預設值是 |
| 文本閱讀順序。可以是 |
| 應該使用的GitBook版本。使用 SemVer 規範，并接受類似于 |
author
作者姓名，在GitBook.com上，這個字段是預先填寫的。
例：
"author" : "victor zhang" description
電子書的描述，預設值是從 README 中提取出來的。在GitBook.com上，這個字段是預先填寫的。
"description" : "Gitbook 教程" direction
文本的方向。可以是 rtl 或 ltr，預設值取決于語言的值。
"direction" : "ltr" gitbook
應該使用的GitBook版本。使用SemVer規範，接受類似于 >=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/dunwu/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": [
"splitter"
] 添加新插件之後需要運作
gitbook install
來安裝新的插件
去除自帶插件
Gitbook 預設帶有 5 個插件：
- highlight
- search
- sharing
- font-settings
- livereload
"plugins": [
"-search"
] 除了
root
屬性之外，您可以指定 Readme，Summary，Glossary 和 Languages 的名稱（而不是使用預設名稱，如README.md）。這些檔案必須在項目的根目錄下（或
root
的根目錄，如果你在
book.json
中配置了
root
屬性）。不接受的路徑，如：
dir / MY_README.md
| Readme 檔案名（預設值是 |
| Summary 檔案名（預設值是 |
| Glossary 檔案名（預設值是 |
| Languages 檔案名（預設值是 |
可以使用
book.json
中的一組選項來定制PDF輸出：
| Variable | Description |
|---|---|
| 将頁碼添加到每個頁面的底部（預設為 true） |
| 基本字型大小（預設是 12） |
| 基本字型樣式（預設是 |
| 頁面尺寸，選項有： |
| 上邊界（預設值是 56） |
| 下邊界（預設值是 56） |
| 右邊界（預設值是 62） |
| 左邊界（預設值是 62） |
生成電子書
GitBook 可以生成一個網站，但也可以輸出内容作為電子書（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 發行版中，節點被安裝為 nodejs，您需要手動建立一個符号連結：
$sudo ln -s /usr/bin/nodejs /usr/bin/node OS X
下載下傳
。将
calibre.app
移動到應用程式檔案夾後，建立一個符号連結到
ebook-convert
工具：
$ sudo ln -s ~/Applications/calibre.app/Contents/MacOS/ebook-convert /usr/bin 您可以使用 $PATH 中的任何目錄替換
/usr/bin
封面
封面用于所有電子書格式。您可以自己提供一個，也可以使用
autocover plugin生成一個。
要提供封面，請将
cover.jpg
檔案放在書本的根目錄下。添加一個
cover_small.jpg
将指定一個較小版本的封面。封面應為
JPEG
檔案。
好的封面應該遵守以下準則：
-
cover.jpg
cover_small.jpg
- 沒有邊界
- 清晰可見的書名
- 任何重要的文字應該在小版本中可見
Gitbook 部署
托管到 gitbook.com
建立新書
如下圖所示，根據個人需求，選擇一個模闆建立你的電子書。
設定書的基本資訊
clone 到本地
Gitbook.com 會為每本書建立一個 git 倉庫。
如下圖所示，拷貝 git 位址，然後
git clone
到本地。
釋出
在本地按照 Gitbook 規範編輯電子書，然後
git push
到 Gitbook 的遠端倉庫。
預設通路位址是：https://使用者名.gitbooks.io/項目名/content/
例如：我的使用者名為 dunwu，一個電子書項目名為 test，則通路路徑是：
https://dunwu.gitbooks.io/test/content/
當然，如果你有自己的域名，也可以設定 Domains 選項，來指定通路路徑為你的域。
托管到 Github
如果你不希望使用 Gitbook 的倉庫，而是想直接使用 Github 的倉庫，也是可以的。
首先，你需要綁定你的 Github 賬号。最簡單的方式當然就是登入 Gitbook.com 時使用 Github 賬号登入方式了。否則，你也可以在 Account Settings 中的 Github 設定選項中去進行綁定。
綁定了 Github 賬号後，你可以在建立電子書時，選擇從一個指定的 Github 倉庫導入電子書項目。參考下圖：
隻要你指定的 Github 倉庫中的文檔内容符合 Gitbook 規範，Gitbook 就會自動根據你的每次更新去建構生成電子書網站。
預設通路位址是：
https://Github使用者名.gitbooks.io/Github 倉庫/content/ 例如：我的使用者名為 dunwu，Github 倉庫名為 gitbook-notes，則通路路徑是：
https://dunwu.gitbooks.io/gitbook-notes/content/托管到 Github Pages
也許你以前也了解 Github 的一個功能：
GitHub Pages。它允許使用者在 GitHub 倉庫托管你的個人、組織或項目的靜态頁面（自動識别 html、css、javascript）。
建立 xxx.github.io 倉庫
要使用這個特性，首先，你必須建立一個嚴格遵循以下命名要求的倉庫：
Github賬号名.github.io
舉例，我的 Github 賬号為 dunwu，則這個倉庫應該叫
dunwu.github.io
。通常，這個倉庫被用來作為個人或組織的部落格。
建立 gh-pages 分支
完成第1步後，在任意一個 Github 倉庫中建立一個名為
gh-pages
的分支。隻要
gh-pages
中的内容符合一個靜态站點要求，就可以在如下位址中進行通路：
https://Github使用者名.gitbooks.io/Github 倉庫
。例如：我的一個 Github 倉庫名為 react-notes，則通路路徑是：
https://dunwu.github.io/react-notes
自動化釋出到 gh-pages
如果每次都手動 git push 到遠端 gh-pages 分支，略有點麻煩。
怎麼實作自動化釋出呢？
有兩種方法：
使用 gh-pages 插件
如果你了解 Nodejs，那麼最簡單的釋出方式就是使用
gh-pages
插件。
先在本地安裝插件
$ npm i -D gh-pages 然後，在 package.json 檔案中添加腳本指令：
如下：
-d
指令參數後面是要釋出的靜态站點内容的目錄
"scripts": {
"deploy": "gh-pages -d build"
}, 腳本
寫一個執行 git 指令的腳本就搞定了。
下面的腳本無論是在 bat 或 sh 腳本中都可以執行。
cd build
git init
git checkout -b gh-pages
git add .
git commit -am "Update"
git push [email protected]:dunwu/gitbook-notes gh-pages --force" 資源
官方資源
教程資源
- gitbook-use by zhangjikai