GitBook

概述
GitBook 是使用 GitHub / Git 和 Markdown（或AsciiDoc）構(gòu)建漂亮?xí)拿钚泄ぞ撸ê蚇ode.js庫）。

GitBook 可以將您的內(nèi)容作為網(wǎng)站（可定制和可擴(kuò)展）或電子書（PDF，ePub或Mobi）輸出。

GitBook.com 是使用 GitBook 格式創(chuàng)建和托管圖書的在線平臺(tái)。它提供托管，協(xié)作功能和易于使用的編輯器。

GitBook 安裝
本地安裝
環(huán)境要求
安裝 GitBook 是很簡(jiǎn)單的。您的系統(tǒng)只需要滿足這兩個(gè)要求：

NodeJS（推薦使用v4.0.0及以上版本）
Windows，Linux，Unix 或 Mac OS X
通過NPM安裝
安裝 GitBook 的最好辦法是通過 NPM。在終端提示符下，只需運(yùn)行以下命令即可安裝 GitBook：

$ npm install gitbook-cli -g
gitbook-cli 是 GitBook 的一個(gè)命令行工具。它將自動(dòng)安裝所需版本的 GitBook 來構(gòu)建一本書。

執(zhí)行下面的命令，查看 GitBook 版本，以驗(yàn)證安裝成功。

$ gitbook -V
安裝歷史版本
gitbook-cli 可以輕松下載并安裝其他版本的GitBook來測(cè)試您的書籍：

$ gitbook fetch beta
使用 gitbook ls-remote 會(huì)列舉可以下載的版本。

創(chuàng)建一本書
初始化
GitBook可以設(shè)置一個(gè)樣板書：

$ gitbook init
如果您希望將書籍創(chuàng)建到一個(gè)新目錄中，可以通過運(yùn)行 gitbook init ./directory 這樣做。

構(gòu)建
使用下面的命令，會(huì)在項(xiàng)目的目錄下生成一個(gè) _book 目錄，里面的內(nèi)容為靜態(tài)站點(diǎn)的資源文件：

$ gitbook build
Debugging
您可以使用選項(xiàng) --log=debug 和 --debug 來獲取更好的錯(cuò)誤消息（使用堆棧跟蹤）。例如：

$ gitbook build ./ --log=debug --debug
啟動(dòng)服務(wù)
使用下列命令會(huì)運(yùn)行一個(gè) web 服務(wù), 通過 http://localhost:4000/ 可以預(yù)覽書籍

$ gitbook serve
GitBook 命令
這里主要介紹一下 GitBook 的命令行工具 gitbook-cli 的一些命令, 首先說明兩點(diǎn):

gitbook-cli 和 gitbook 是兩個(gè)軟件
gitbook-cli 會(huì)將下載的 gitbook 的不同版本放到 ~/.gitbook中, 可以通過設(shè)置GITBOOK_DIR環(huán)境變量來指定另外的文件夾
列出 gitbook 所有的命令

gitbook help
輸出 gitbook-cli 的幫助信息

gitbook --help
生成靜態(tài)網(wǎng)頁

gitbook build
生成靜態(tài)網(wǎng)頁并運(yùn)行服務(wù)器

gitbook serve
生成時(shí)指定gitbook的版本, 本地沒有會(huì)先下載

gitbook build --gitbook=2.0.1
列出本地所有的gitbook版本

gitbook ls
列出遠(yuǎn)程可用的gitbook版本

gitbook ls-remote
安裝對(duì)應(yīng)的gitbook版本

gitbook fetch 標(biāo)簽/版本號(hào)
更新到gitbook的最新版本

gitbook update
卸載對(duì)應(yīng)的gitbook版本

gitbook uninstall 2.0.1
指定log的級(jí)別

gitbook build --log=debug
輸出錯(cuò)誤信息

gitbook builid --debug
Gitbook 目錄結(jié)構(gòu)
GitBook 項(xiàng)目結(jié)構(gòu)
GitBook使用簡(jiǎn)單的目錄結(jié)構(gòu)。在 SUMMARY （即 SUMMARY.md 文件）中列出的所有 Markdown / Asciidoc 文件將被轉(zhuǎn)換為 HTML。多語言書籍結(jié)構(gòu)略有不同。

一個(gè)基本的 GitBook 電子書結(jié)構(gòu)通常如下：

.
├── book.json
├── README.md
├── SUMMARY.md
├── chapter-1/
| ├── README.md
| └── something.md
└── chapter-2/
├── README.md
└── something.md
GitBook 特殊文件的功能：

文件 描述
book.json 配置數(shù)據(jù) (optional)
README.md 電子書的前言或簡(jiǎn)介 (required)
SUMMARY.md 電子書目錄 (optional)
GLOSSARY.md 詞匯/注釋術(shù)語列表 (optional)
靜態(tài)文件和圖片
靜態(tài)文件是在 SUMMARY.md 中未列出的文件。除非被忽略，否則所有靜態(tài)文件都將復(fù)制到輸出路徑。

忽略文件和文件夾
GitBook將讀取 .gitignore，.bookignore 和 .ignore 文件，以獲取要過濾的文件和文件夾。這些文件中的格式遵循 .gitignore 的規(guī)則：

This is a comment

Ignore the file test.md

test.md

Ignore everything in the directory "bin"

bin/*
項(xiàng)目與子目錄集成
對(duì)于軟件項(xiàng)目，您可以使用子目錄（如 docs/ ）來存儲(chǔ)項(xiàng)目文檔的圖書。您可以配置根選項(xiàng)來指示 GitBook 可以找到該圖書文件的文件夾：

.
├── book.json
└── docs/
├── README.md
└── SUMMARY.md
在 book.json 中配置以下內(nèi)容：

{
"root": "./docs"
}
Summary
GitBook 使用 SUMMARY.md 文件來定義本書的章節(jié)和子章節(jié)的結(jié)構(gòu)。 SUMMARY.md 文件用于生成本書的目錄。

SUMMARY.md 的格式是一個(gè)鏈接列表。鏈接的標(biāo)題將作為章節(jié)的標(biāo)題，鏈接的目標(biāo)是該章節(jié)文件的路徑。

向父章節(jié)添加嵌套列表將創(chuàng)建子章節(jié)。

簡(jiǎn)單示例：

Summary

錨點(diǎn)

目錄中的章節(jié)可以使用錨點(diǎn)指向文件的特定部分。

Summary

Part I

目錄可以分為以標(biāo)題或水平線 ---- 分隔的部分：

Summary

Part I

Part II

  • Last part without title
    Parts 只是章節(jié)組，沒有專用頁面，但根據(jù)主題，它將在導(dǎo)航中顯示。

頁面
Markdown 語法

默認(rèn)情況下，GitBook 的大多數(shù)文件都使用 Markdown 語法。 GitBook 推薦使用這種語法。所使用的語法類似于 GitHub Flavored Markdown syntax 。

此外，你還可以選擇 AsciiDoc 語法。

頁面內(nèi)容示例：

Title of the chapter

This is a great introduction.

Section 1

Markdown will dictates most of your book's structure

Section 2

...
頁面前言

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

description: This is a short description of my page

The content of my page

...
Glossary
允許您指定要顯示為注釋的術(shù)語及其各自的定義。根據(jù)這些術(shù)語，GitBook 將自動(dòng)構(gòu)建索引并突出顯示這些術(shù)語。

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

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

這些選項(xiàng)在 book.json 文件中指定。對(duì)于不熟悉 JSON 語法的作者，您可以使用 JSONlint 等工具驗(yàn)證語法。

常規(guī)設(shè)置
變量 描述
root 包含所有圖書文件的根文件夾的路徑，除了 book.json
structure 指定自述文件，摘要，詞匯表等的路徑，參考 Structure paragraph.
title 您的書名，默認(rèn)值是從 README 中提取出來的。在 GitBook.com 上，這個(gè)字段是預(yù)填的。
description 您的書籍的描述，默認(rèn)值是從 README 中提取出來的。在 GitBook.com 上，這個(gè)字段是預(yù)填的。
author 作者名。在GitBook.com上，這個(gè)字段是預(yù)填的。
isbn 國際標(biāo)準(zhǔn)書號(hào) ISBN
language 本書的語言類型 —— ISO code 。默認(rèn)值是 en
direction 文本閱讀順序?？梢允?rtl （從右向左）或 ltr （從左向右），默認(rèn)值依賴于 language 的值。
gitbook 應(yīng)該使用的GitBook版本。使用 SemVer 規(guī)范，并接受類似于 “> = 3.0.0” 的條件。
author

作者姓名，在GitBook.com上，這個(gè)字段是預(yù)先填寫的。

例：

"author" : "victor zhang"
description

電子書的描述，默認(rèn)值是從 README 中提取出來的。在GitBook.com上，這個(gè)字段是預(yù)先填寫的。

例：

"description" : "Gitbook 教程"
direction

文本的方向?？梢允?rtl 或 ltr，默認(rèn)值取決于語言的值。

例：

"direction" : "ltr"
gitbook

應(yīng)該使用的GitBook版本。使用SemVer規(guī)范，接受類似于 >=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

在左側(cè)導(dǎo)航欄添加鏈接信息

例：

"links" : {
"sidebar" : {
"Home" : "https://github.com/atlantis1024/gitbook-notes"
}
}
root

包含所有圖書文件的根文件夾的路徑， book.json 文件除外。

例：

"root" : "./docs",
structure

指定 Readme、Summary、Glossary 和 Languages 對(duì)應(yīng)的文件名。

styles

自定義頁面樣式， 默認(rèn)情況下各generator對(duì)應(yīng)的css文件

例：

"styles": {
"website": "styles/website.css",
"ebook": "styles/ebook.css",
"pdf": "styles/pdf.css",
"mobi": "styles/mobi.css",
"epub": "styles/epub.css"
}
例如要使 h1、h2 標(biāo)簽有下邊框， 可以在 website.css 中設(shè)置

h1 , h2{
border-bottom: 1px solid #EFEAEA;
}
title

電子書的書名，默認(rèn)值是從 README 中提取出來的。在 GitBook.com 上，這個(gè)字段是預(yù)先填寫的。

例：

"title" : "gitbook-notes",
plugins
插件及其配置在 book.json 中指定。有關(guān)詳細(xì)信息。

自 3.0.0 版本開始，GitBook 可以使用主題。有關(guān)詳細(xì)信息，請(qǐng)參閱 the theming section 。

變量 描述
plugins 要加載的插件列表
pluginsConfig 插件的配置
添加插件
"plugins": [
"splitter"
]
添加新插件之后需要運(yùn)行 gitbook install 來安裝新的插件

去除自帶插件
Gitbook 默認(rèn)帶有 5 個(gè)插件：

highlight
search
sharing
font-settings
livereload
"plugins": [
"-search"
]
structure
除了 root 屬性之外，您可以指定 Readme，Summary，Glossary 和 Languages 的名稱（而不是使用默認(rèn)名稱，如README.md）。這些文件必須在項(xiàng)目的根目錄下（或 root 的根目錄，如果你在 book.json 中配置了 root 屬性）。不接受的路徑，如：dir / MY_README.md。

變量 描述
structure.readme Readme 文件名（默認(rèn)值是 README.md ）
structure.summary Summary 文件名（默認(rèn)值是 SUMMARY.md ）
structure.glossary Glossary 文件名（默認(rèn)值是 GLOSSARY.md ）
structure.languages Languages 文件名（默認(rèn)值是 LANGS.md ）
pdf
可以使用 book.json 中的一組選項(xiàng)來定制PDF輸出：

Variable Description
pdf.pageNumbers 將頁碼添加到每個(gè)頁面的底部（默認(rèn)為 true）
pdf.fontSize 基本字體大?。J(rèn)是 12）
pdf.fontFamily 基本字體樣式（默認(rèn)是 Arial）
pdf.paperSize 頁面尺寸，選項(xiàng)有： 'a0', 'a1', 'a2', 'a3', 'a4', 'a5', 'a6', 'b0', 'b1', 'b2', 'b3', 'b4', 'b5', 'b6', 'legal', 'letter' （默認(rèn)值是 a4）
pdf.margin.top 上邊界（默認(rèn)值是 56）
pdf.margin.bottom 下邊界（默認(rèn)值是 56）
pdf.margin.right 右邊界（默認(rèn)值是 62）
pdf.margin.left 左邊界（默認(rèn)值是 62）
生成電子書
GitBook 可以生成一個(gè)網(wǎng)站，但也可以輸出內(nèi)容作為電子書（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 發(fā)行版中，節(jié)點(diǎn)被安裝為 nodejs，您需要手動(dòng)創(chuàng)建一個(gè)符號(hào)鏈接：

$sudo ln -s /usr/bin/nodejs /usr/bin/node
OS X
下載 Calibre application。將 calibre.app 移動(dòng)到應(yīng)用程序文件夾后，創(chuàng)建一個(gè)符號(hào)鏈接到 ebook-convert 工具：

sudo ln -s ~/Applications/calibre.app/Contents/MacOS/ebook-convert /usr/bin 您可以使用PATH 中的任何目錄替換 /usr/bin 。

封面
封面用于所有電子書格式。您可以自己提供一個(gè)，也可以使用 autocover plugin 生成一個(gè)。

要提供封面，請(qǐng)將 cover.jpg 文件放在書本的根目錄下。添加一個(gè) cover_small.jpg 將指定一個(gè)較小版本的封面。封面應(yīng)為 JPEG 文件。

好的封面應(yīng)該遵守以下準(zhǔn)則：

cover.jpg 的尺寸為 1800x2360 像素，cover_small.jpg 為 200x262
沒有邊界
清晰可見的書名
任何重要的文字應(yīng)該在小版本中可見
Gitbook 部署
托管到 gitbook.com
GitBook.com 是使用 GitBook 格式創(chuàng)建和托管圖書的在線平臺(tái)。它提供托管，協(xié)作功能和易于使用的編輯器。

創(chuàng)建新書

如下圖所示，根據(jù)個(gè)人需求，選擇一個(gè)模板創(chuàng)建你的電子書。

設(shè)置書的基本信息

clone 到本地

Gitbook.com 會(huì)為每本書創(chuàng)建一個(gè) git 倉庫。

如下圖所示，拷貝 git 地址，然后 git clone 到本地。

發(fā)布

在本地按照 Gitbook 規(guī)范編輯電子書，然后 git push 到 Gitbook 的遠(yuǎn)程倉庫。

默認(rèn)訪問地址是：https://用戶名.gitbooks.io/項(xiàng)目名/content/

例如：我的用戶名為 atlantis1024，一個(gè)電子書項(xiàng)目名為 test，則訪問路徑是： https://atlantis1024.gitbooks.io/test/content/

當(dāng)然，如果你有自己的域名，也可以設(shè)置 Domains 選項(xiàng)，來指定訪問路徑為你的域。

托管到 Github
如果你不希望使用 Gitbook 的倉庫，而是想直接使用 Github 的倉庫，也是可以的。

首先，你需要綁定你的 Github 賬號(hào)。最簡(jiǎn)單的方式當(dāng)然就是登錄 Gitbook.com 時(shí)使用 Github 賬號(hào)登錄方式了。否則，你也可以在 Account Settings 中的 Github 設(shè)置選項(xiàng)中去進(jìn)行綁定。

綁定了 Github 賬號(hào)后，你可以在新建電子書時(shí)，選擇從一個(gè)指定的 Github 倉庫導(dǎo)入電子書項(xiàng)目。參考下圖：

只要你指定的 Github 倉庫中的文檔內(nèi)容符合 Gitbook 規(guī)范，Gitbook 就會(huì)自動(dòng)根據(jù)你的每次更新去構(gòu)建生成電子書網(wǎng)站。

默認(rèn)訪問地址是：

https://Github用戶名.gitbooks.io/Github 倉庫/content/
例如：我的用戶名為 atlantis1024，Github 倉庫名為 gitbook-notes，則訪問路徑是：

https://atlantis1024.gitbooks.io/gitbook-notes/content/

托管到 Github Pages
也許你以前也了解 Github 的一個(gè)功能： GitHub Pages 。它允許用戶在 GitHub 倉庫托管你的個(gè)人、組織或項(xiàng)目的靜態(tài)頁面（自動(dòng)識(shí)別 html、css、javascript）。

建立 xxx.github.io 倉庫

要使用這個(gè)特性，首先，你必須建立一個(gè)嚴(yán)格遵循以下命名要求的倉庫：Github賬號(hào)名.github.io舉例，我的 Github 賬號(hào)為 atlantis1024，則這個(gè)倉庫應(yīng)該叫 atlantis1024.github.io。通常，這個(gè)倉庫被用來作為個(gè)人或組織的博客。

建立 gh-pages 分支

完成第1步后，在任意一個(gè) Github 倉庫中建立一個(gè)名為 gh-pages 的分支。只要 gh-pages 中的內(nèi)容符合一個(gè)靜態(tài)站點(diǎn)要求，就可以在如下地址中進(jìn)行訪問：https://Github用戶名.gitbooks.io/Github 倉庫 。例如：我的一個(gè) Github 倉庫名為 react-notes，則訪問路徑是：https://atlantis1024.github.io/react-notes

自動(dòng)化發(fā)布到 gh-pages

如果每次都手動(dòng) git push 到遠(yuǎn)程 gh-pages 分支，略有點(diǎn)麻煩。

怎么實(shí)現(xiàn)自動(dòng)化發(fā)布呢？

有兩種方法：

使用 gh-pages 插件

如果你了解 Nodejs，那么最簡(jiǎn)單的發(fā)布方式就是使用 gh-pages 插件。

先在本地安裝插件

$ npm i -D gh-pages
然后，在 package.json 文件中添加腳本命令：

如下：-d 命令參數(shù)后面是要發(fā)布的靜態(tài)站點(diǎn)內(nèi)容的目錄

"scripts": {
"deploy": "gh-pages -d build"
},
腳本

寫一個(gè)執(zhí)行 git 命令的腳本就搞定了。

下面的腳本無論是在 bat 或 sh 腳本中都可以執(zhí)行。

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 官網(wǎng)
Gitbook Toolchain 文檔
Gitbook 幫助中心
教程資源
gitbook-use by zhangjikai
工具
Gitbook 編輯器

?著作權(quán)歸作者所有,轉(zhuǎn)載或內(nèi)容合作請(qǐng)聯(lián)系作者
【社區(qū)內(nèi)容提示】社區(qū)部分內(nèi)容疑似由AI輔助生成，瀏覽時(shí)請(qǐng)結(jié)合常識(shí)與多方信息審慎甄別。
平臺(tái)聲明：文章內(nèi)容（如有圖片或視頻亦包括在內(nèi)）由作者上傳并發(fā)布，文章內(nèi)容僅代表作者本人觀點(diǎn)，簡(jiǎn)書系信息發(fā)布平臺(tái)，僅提供信息存儲(chǔ)服務(wù)。

相關(guān)閱讀更多精彩內(nèi)容

  • 概述 GitBook 是使用 GitHub / Git 和 Markdown（或AsciiDoc）構(gòu)建漂亮?xí)拿?..
    輝這樣說閱讀 3,114評(píng)論 0贊 4
  • 本文詳細(xì)講解了 Gitbook 生成電子書的完整過程，內(nèi)容包括：安裝、命令、配置、文檔結(jié)構(gòu)、生成電子書、部署。限于...
    靜默虛空閱讀 11,474評(píng)論 9贊 138
  • 1. GitHub 1.1. 創(chuàng)建賬戶 https://github.com/ 在上面注冊(cè)賬戶: gitexam...
    蝴蝶泉nq閱讀 5,076評(píng)論 1贊 3
  • Gitbook是一個(gè)命令行工具，可以把你的Markdown文件匯集成電子書，并提供PDF等多種格式輸出。你可以把G...
    陳云峰閱讀 6,506評(píng)論 1贊 7
  • 第三十五章 早起下樓，安多敲開了查爾斯臥室的門，她取出一個(gè)包裝和...
    青山一木閱讀 193評(píng)論 0贊 0

友情鏈接更多精彩內(nèi)容