使用 Gitbook 打造你的電子書

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

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

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

我的 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.mdtest.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 chapterThis is a great introduction.## Section 1Markdown will dictates _most_ of your **books structure**## Section 2...

頁面前言

頁面可以包含一個可選的前言。它可以用於定義頁面的描述。前面的事情必須是文件中的第一件事，必須採取在三虛線之間設置的有效YAML的形式。這是一個基本的例子：

---description: This is a short description of my page---# The content of my page...

Glossary

允許您指定要顯示為注釋的術語及其各自的定義。根據這些術語，GitBook 將自動構建索引並突出顯示這些術語。

GLOSSARY.md 的格式是 h2 標題的列表，以及描述段落：

## TermDefinition for this term## Another termWith its definition, this can contain bold textand all other kinds of inline markup ...

Gitbook 配置

GitBook 允許您使用靈活的配置自定義您的電子書。

這些選項在 book.json 文件中指定。對於不熟悉 JSON 語法的作者，您可以使用 JSONlint 等工具驗證語法。

常規設置

author

作者姓名，在http://GitBook.com上，這個欄位是預先填寫的。

例：

"author" : "victor zhang"

description

電子書的描述，默認值是從 README 中提取出來的。在http://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 中提取出來的。在 http://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 部署

託管到 http://gitbook.com

[http://GitBook.com](https://www.gitbook.com/ ) 是使用 GitBook 格式創建和託管圖書的在線平台。它提供託管，協作功能和易於使用的編輯器。

創建新書

如下圖所示，根據個人需求，選擇一個模板創建你的電子書。

設置書的基本信息

clone 到本地

http://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 賬號。最簡單的方式當然就是登錄 http://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）。

建立 http://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 buildgit initgit checkout -b gh-pagesgit 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 編輯器

作者： 靜默虛空

鏈接：https://www.imooc.com/article/22889

來源：慕課網

本文原創發佈於慕課網 ，轉載請註明出處，謝謝合作

推薦閱讀：

【有獎問答】當我們談論Java時，我們都談些什麼？

10 個技巧促使你的 Git 的技能上一個台階

如何做出良好用戶體驗的動效設計

如何解決MaxScale2.2版本無法load MySQL用戶的問題

三分鐘學會用 js + css3 打造酷炫3D相冊