使用 Gitbook 打造你的電子書

本文詳細講解了 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中, 可以通過設定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 特殊檔案的功能：

靜態檔案和圖片

靜態檔案是在 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 等工具驗證語法。

常規設定

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: 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"
]

structure

除了 root 屬性之外，您可以指定 Readme，Summary，Glossary 和 Languages 的名稱（而不是使用預設名稱，如README.md）。這些檔案必須在專案的根目錄下（或 root 的根目錄，如果你在 book.json 中配置了 root 屬性）。不接受的路徑，如：dir / MY_README.md。

pdf

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

生成電子書

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/

例如：我的使用者名稱為 atlantis1024，一個電子書專案名為 test，則訪問路徑是： https://atlantis1024.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/

例如：我的使用者名稱為 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"
git push git@github.com:atlantis1024/gitbook-notes gh-pages --force"

資源

官方資源

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

教程資源

• gitbook-use by zhangjikai

工具

• Gitbook 編輯器

作者：靜默虛空
歡迎任何形式的轉載，但請務必註明出處。

限於本人水平，如果文章和程式碼有表述不當之處，還請不吝賜教。

轉載來自：http://www.cnblogs.com/jingmoxukong/p/7453155.html