概述
GitBook 是使用 GitHub / Git 和 Markdown（或AsciiDoc）構建漂亮書籍的命令行工具（和Node.js庫）。
GitBook 可以將您的內容作為網站（可定制和可擴展）或電子書（PDF，ePub或Mobi）輸出。
GitBook.com?是使用 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-cli?的一些命令, 首先說明兩點:
gitbook-cli?和?gitbook?是兩個軟件
gitbook-cli?會將下載的 gitbook 的不同版本放到?~/.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版本
gitbookls -remote
安裝對應的gitbook版本
gitbook fetch 標簽/版本號
更新到gitbook的最新版本
gitbook update
卸載對應的gitbook版本
gitbook uninstall 2.0.1
指定log的級別
gitbook build --log=debug
輸出錯誤信息
gitbook builid --debug
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 特殊文件的功能：
文件描述
book.json配置數據 (optional)
README.md電子書的前言或簡介 (required)
SUMMARY.md電子書目錄 (optional)
GLOSSARY.md詞匯/注釋術語列表 (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"
}
GitBook 使用SUMMARY.md文件來定義本書的章節和子章節的結構。SUMMARY.md?文件用于生成本書的目錄。
SUMMARY.md的格式是一個鏈接列表。鏈接的標題將作為章節的標題，鏈接的目標是該章節文件的路徑。
向父章節添加嵌套列表將創建子章節。
簡單示例：
# Summary
* [Part I](part1/README.md)
* [Writingisnice](part1/writing.md)
* [GitBookisnice](part1/gitbook.md)
* [Part II](part2/README.md)
? ? * [We love feedback](part2/feedback_please.md)
* [Better toolsforauthors](part2/better_tools.md)
每章都有一個專用頁面（part#/README.md），并分為子章節。
錨點
目錄中的章節可以使用錨點指向文件的特定部分。
# Summary
### Part I
* [Part I](part1/README.md)
* [Writingisnice](part1/README.md#writing)
* [GitBookisnice](part1/README.md#gitbook)
* [Part II](part2/README.md)
* [We love feedback](part2/README.md#feedback)
* [Better toolsforauthors](part2/README.md#tools)
部分
目錄可以分為以標題或水平線?----?分隔的部分：
# Summary
### Part I
* [Writingisnice](part1/writing.md)
* [GitBookisnice](part1/gitbook.md)
### Part II
* [We love feedback](part2/feedback_please.md)
* [Better toolsforauthors](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
Thisisa great introduction.
## Section 1
Markdown will dictates _most_ofyour **book's structure**
## Section 2
...
頁面前言
頁面可以包含一個可選的前言。它可以用于定義頁面的描述。前面的事情必須是文件中的第一件事，必須采取在三虛線之間設置的有效YAML的形式。這是一個基本的例子：
---
description: Thisisashortdescriptionofmy page
---
# The content of my page
...
允許您指定要顯示為注釋的術語及其各自的定義。根據這些術語，GitBook 將自動構建索引并突出顯示這些術語。
GLOSSARY.md的格式是?h2?標題的列表，以及描述段落：
## Term
Definitionforthis term
## Another term
Withit's definition, this can contain bold text
andall other kindsofinline markup ...
GitBook 允許您使用靈活的配置自定義您的電子書。
這些選項在?book.json?文件中指定。對于不熟悉 JSON 語法的作者，您可以使用?JSONlint?等工具驗證語法。
變量描述
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?規范，并接受類似于?“> = 3.0.0”?的條件。
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/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:1pxsolid#EFEAEA;
}
title
電子書的書名，默認值是從 README 中提取出來的。在 GitBook.com 上，這個字段是預先填寫的。
例：
"title":"gitbook-notes",
插件及其配置在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"
]
除了root?屬性之外，您可以指定 Readme，Summary，Glossary 和 Languages 的名稱（而不是使用默認名稱，如README.md）。這些文件必須在項目的根目錄下（或?root?的根目錄，如果你在?book.json?中配置了root?屬性）。不接受的路徑，如：dir / MY_README.md。
變量描述
structure.readmeReadme 文件名（默認值是README.md?）
structure.summarySummary 文件名（默認值是SUMMARY.md?）
structure.glossaryGlossary 文件名（默認值是GLOSSARY.md?）
structure.languagesLanguages 文件名（默認值是LANGS.md?）
可以使用book.json?中的一組選項來定制PDF輸出：
VariableDescription
pdf.pageNumbers將頁碼添加到每個頁面的底部（默認為 true）
pdf.fontSize基本字體大小（默認是 12）
pdf.fontFamily基本字體樣式（默認是?Arial）
pdf.paperSize頁面尺寸，選項有：'a0', 'a1', 'a2', 'a3', 'a4', 'a5', 'a6', 'b0', 'b1', 'b2', 'b3', 'b4', 'b5', 'b6', 'legal', 'letter'（默認值是?a4）
pdf.margin.top上邊界（默認值是 56）
pdf.margin.bottom下邊界（默認值是 56）
pdf.margin.right右邊界（默認值是 62）
pdf.margin.left左邊界（默認值是 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可以用來生成電子書（epub，mobi，pdf）。
GNU/Linux
$sudoaptitude install calibre
在一些 GNU / Linux 發行版中，節點被安裝為 nodejs，您需要手動創建一個符號鏈接：
$sudoln-s /usr/bin/nodejs /usr/bin/node
OS X
下載Calibre application。將?calibre.app?移動到應用程序文件夾后，創建一個符號鏈接到?ebook-convert?工具：
$sudoln -s ~/Applications/calibre.app/Contents/MacOS/ebook-convert /usr/bin
您可以使用 $PATH 中的任何目錄替換/usr/bin。
封面用于所有電子書格式。您可以自己提供一個，也可以使用autocover plugin?生成一個。
要提供封面，請將?cover.jpg?文件放在書本的根目錄下。添加一個?cover_small.jpg?將指定一個較小版本的封面。封面應為?JPEG?文件。
好的封面應該遵守以下準則：
cover.jpg?的尺寸為 1800x2360 像素，cover_small.jpg?為 200x262
沒有邊界
清晰可見的書名
任何重要的文字應該在小版本中可見
GitBook.com?是使用 GitBook 格式創建和托管圖書的在線平臺。它提供托管，協作功能和易于使用的編輯器。
創建新書
如下圖所示，根據個人需求，選擇一個模板創建你的電子書。
設置書的基本信息
clone 到本地
Gitbook.com 會為每本書創建一個 git 倉庫。
如下圖所示，拷貝 git 地址，然后?git clone?到本地。
發布
在本地按照 Gitbook 規范編輯電子書，然后?git push?到 Gitbook 的遠程倉庫。
默認訪問地址是：https://用戶名.gitbooks.io/項目名/content/
例如：我的用戶名為 atlantis1024，一個電子書項目名為 test，則訪問路徑是：?https://atlantis1024.gitbooks.io/test/content/
當然，如果你有自己的域名，也可以設置 Domains 選項，來指定訪問路徑為你的域。
如果你不希望使用 Gitbook 的倉庫，而是想直接使用 Github 的倉庫，也是可以的。
首先，你需要綁定你的 Github 賬號。最簡單的方式當然就是登錄 Gitbook.com 時使用 Github 賬號登錄方式了。否則，你也可以在 Account Settings 中的 Github 設置選項中去進行綁定。
綁定了 Github 賬號后，你可以在新建電子書時，選擇從一個指定的 Github 倉庫導入電子書項目。參考下圖：
只要你指定的 Github 倉庫中的文檔內容符合 Gitbook 規范，Gitbook 就會自動根據你的每次更新去構建生成電子書網站。
默認訪問地址是：
https://Github用戶名.gitbooks.io/Github 倉庫/content/
例如：我的用戶名為 atlantis1024，Github 倉庫名為 gitbook-notes，則訪問路徑是：
https://atlantis1024.gitbooks.io/gitbook-notes/content/
托管到 Github Pages
也許你以前也了解 Github 的一個功能：?GitHub Pages?。它允許用戶在 GitHub 倉庫托管你的個人、組織或項目的靜態頁面（自動識別 html、css、javascript）。
建立 xxx.github.io 倉庫
要使用這個特性，首先，你必須建立一個嚴格遵循以下命名要求的倉庫：Github賬號名.github.io舉例，我的 Github 賬號為 atlantis1024，則這個倉庫應該叫?atlantis1024.github.io。通常，這個倉庫被用來作為個人或組織的博客。
建立 gh-pages 分支
完成第1步后，在任意一個 Github 倉庫中建立一個名為?gh-pages?的分支。只要?gh-pages?中的內容符合一個靜態站點要求，就可以在如下地址中進行訪問：https://Github用戶名.gitbooks.io/Github 倉庫?。例如：我的一個 Github 倉庫名為 react-notes，則訪問路徑是：https://atlantis1024.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"
gitpushgit@github.com:atlantis1024/gitbook-notes gh-pages --force"
gitbook-use?by zhangjikai
