使用 Gitbook 打造你的電子書

本文詳細講解了 Gitbook 生成電子書的完整過程，內容包括：安裝、命令、配置、文檔結構、生成電子書、部署。

限於篇幅，本文不介紹任何 Gitbook 定製化頁面的內容。

想看看 Gitbook 在線電子書效果，請猛戳這裏：gitbook-notes

:notebook: 本文已歸檔到：「blog」

概述

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中, 能夠經過設置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 特殊文件的功能：

文件	描述
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"
}
複製代碼

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 容許您使用靈活的配置自定義您的電子書。

這些選項在 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/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	要加載的插件列表
pluginsConfig	插件的配置

添加插件

"plugins": [
    "splitter"
]
複製代碼

添加新插件以後須要運行 gitbook install 來安裝新的插件

去除自帶插件

Gitbook 默認帶有 5 個插件：

• highlight
• search
• sharing
• font-settings
• livereload

"plugins": [
    "-search"
]
複製代碼

structure

除了 root 屬性以外，您能夠指定 Readme，Summary，Glossary 和 Languages 的名稱（而不是使用默認名稱，如 README.md）。這些文件必須在項目的根目錄下（或 root 的根目錄，若是你在 book.json 中配置了 root 屬性）。不接受的路徑，如：dir / MY_README.md。

變量	描述
structure.readme	Readme 文件名（默認值是 README.md ）
structure.summary	Summary 文件名（默認值是 SUMMARY.md ）
structure.glossary	Glossary 文件名（默認值是 GLOSSARY.md ）
structure.languages	Languages 文件名（默認值是 LANGS.md ）

pdf

可使用 book.json 中的一組選項來定製 PDF 輸出：

Variable	Description
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

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 application。將 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 的尺寸爲 1800x2360 像素，cover_small.jpg 爲 200x262
• 沒有邊界
• 清晰可見的書名
• 任何重要的文字應該在小版本中可見

Gitbook 部署

託管到 gitbook.com

GitBook.com 是使用 GitBook 格式建立和託管圖書的在線平臺。它提供託管，協做功能和易於使用的編輯器。

建立新書

以下圖所示，根據我的需求，選擇一個模板建立你的電子書。

設置書的基本信息

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，則訪問路徑是：

dunwu.gitbooks.io/gitbook-not…

託管到 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 git@github.com:dunwu/gitbook-notes gh-pages --force" 複製代碼

參考資料

官方資源

• Gitbook Github
• Gitbook 官網
• Gitbook Toolchain 文檔
• Gitbook 幫助中心

教程資源

• gitbook-use by zhangjikai

工具

• Gitbook 編輯器