gitbook 入門教程之使用 gitbook-cli 開發電子書

雪之夢技術驛站發表於2019-04-03

gitbook 生成電子書主要有三種方式:

gitbook-cli 命令列操作,簡潔高效,適合從事軟體開發的相關人員.
gitbook-editor 編輯器操作,視覺化編輯,適合無程式設計經驗的文學創作者.
gitbook.com 官網操作,線上編輯實時釋出,適合無本地環境且科學上網的體驗者.

本文主要講解第一種 gitbook-cli 命令列操作流程,其他兩種見另外兩篇教程.

`gitbook` 的一些常用命令

安裝 `gitbook-cli` 腳手架工具

本機已安裝 node.js 開發環境,安裝完成後執行 gitbook -V 能夠列印出版本資訊,則表示安裝成功.

$ sudo npm install -g gitbook-cli
複製程式碼

關於安裝配置相關問題請參考環境要求

初始化 `gitbook` 專案

初始化專案,按照 gitbook 規範會自動建立 README.md 和 SUMMARY.md 兩個檔案,具體用途見下文.

其實 SUMMARY.md 是電子書的章節目錄,gitbook 會初始化相應的檔案目錄結構,所以主要是用於開發初始階段.

$ gitbook init
複製程式碼

啟動 `gitbook` 專案

啟動本地服務,程式無報錯則可以在瀏覽器預覽電子書效果: http://localhost:4000

由於能夠實時預覽電子書效果,並且大多數開發環境搭建在本地而不是遠端伺服器中,所以主要用於開發除錯階段.

$ gitbook serve
複製程式碼

構建 `gitbook` 靜態網頁

構建靜態網頁而不啟動本地伺服器,預設生成檔案存放在 _book/ 目錄,當然輸出目錄是可配置的,暫不涉及,見高階部分.

輸出靜態網頁後可打包上傳到伺服器,也可以上傳到 github 等網站進行託管,因而主要用於釋出準備階段.

$ gitbook build
複製程式碼

章節小結

gitbook init 初始化 README.md 和 SUMMARY.md 兩個檔案.
gitbook build 本地構建但不執行服務,預設輸出到 _book/ 目錄.
gitbook serve 本地構建並執行服務,預設訪問 http://localhost:4000 實時預覽.

# 建立 `gitbook` 演示專案
$ mkdir gitbook-demo

# 初始化專案
$ gitbook init
warn: no summary file in this book 
info: create README.md 
info: create SUMMARY.md 
info: initialization is finished 

# 啟動本地伺服器
$ gitbook serve
Live reload server started on port: 35729
Press CTRL+C to quit ...

info: 7 plugins are installed 
info: loading plugin "livereload"... OK 
info: loading plugin "highlight"... OK 
info: loading plugin "search"... OK 
info: loading plugin "lunr"... OK 
info: loading plugin "sharing"... OK 
info: loading plugin "fontsettings"... OK 
info: loading plugin "theme-default"... OK 
info: found 1 pages 
info: found 0 asset files 
info: >> generation finished with success in 1.2s ! 

Starting server ...
Serving book on http://localhost:4000

# 檢視當前目錄結構
$ tree
.
├── README.md
├── SUMMARY.md
└── _book
    ├── gitbook
    │   ├── fonts
    │   │   └── fontawesome
    │   │       ├── FontAwesome.otf
    │   │       ├── fontawesome-webfont.eot
    │   │       ├── fontawesome-webfont.svg
    │   │       ├── fontawesome-webfont.ttf
    │   │       ├── fontawesome-webfont.woff
    │   │       └── fontawesome-webfont.woff2
    │   ├── gitbook-plugin-fontsettings
    │   │   ├── fontsettings.js
    │   │   └── website.css
    │   ├── gitbook-plugin-highlight
    │   │   ├── ebook.css
    │   │   └── website.css
    │   ├── gitbook-plugin-livereload
    │   │   └── plugin.js
    │   ├── gitbook-plugin-lunr
    │   │   ├── lunr.min.js
    │   │   └── search-lunr.js
    │   ├── gitbook-plugin-search
    │   │   ├── lunr.min.js
    │   │   ├── search-engine.js
    │   │   ├── search.css
    │   │   └── search.js
    │   ├── gitbook-plugin-sharing
    │   │   └── buttons.js
    │   ├── gitbook.js
    │   ├── images
    │   │   ├── apple-touch-icon-precomposed-152.png
    │   │   └── favicon.ico
    │   ├── style.css
    │   └── theme.js
    ├── index.html
    └── search_index.json

11 directories, 27 files
$ 
複製程式碼

`gitbook` 的目錄結構說明

既然要書寫一本電子書,那麼起碼的章節介紹和章節詳情自然是必不可少的.

當然還有標題,作者和聯絡方式等個性化資訊需要指定,如果不指定的話,一旦採用預設配合,八成不符合我們的預期,說不定都會變成匿名電子書?所以配置檔案一般也是需要手動設定的!

真正可選的檔案要數詞彙表了,畢竟不是每一本電子書都有專業詞彙需要去解釋說明.如果在章節詳情順便解釋下涉及到的專業詞彙,那麼自然也就不需要詞彙表檔案了.

簡單解釋下各個檔案的作用:

README.md 是預設首頁檔案,相當於網站的首頁 index.html ,一般是介紹文字或相關導航連結.
SUMMARY.md 是預設概括檔案,主要是根據該檔案內容生成相應的目錄結構,同 README.md 一樣都是被gitbook init 初始化預設建立的重要檔案.
_book 是預設的輸出目錄,存放著原始 markdown 渲染完畢後的 html 檔案,可以直接打包到伺服器充當靜態網站使用.一般是執行 gitbook build 或 gitbook serve 自動生成的.
book.json 是配置檔案,用於個性化調整 gitbook 的相關配置,如定義電子書的標題,封面,作者等資訊.雖然是手動建立但一般是必選的.
GLOSSARY.md 是預設的詞彙表,主要說明專業詞彙的詳細解釋,這樣閱讀到專業詞彙時就會有相應提示資訊,也是手動建立但是可選的.
LANGS.md 是預設的語言檔案,用於國際化版本翻譯,和 GLOSSARY.md 一樣是手動建立但是可選的.

`README.md` 首頁檔案[必須]

編輯 README.md 檔案,隨便寫點內容並啟動本地服務(gitbook serve)實時預覽效果.

`SUMMARY.md` 概括檔案[必須]

先停止本地服務,編輯章節目錄結構,然後重新再初始化(gitbook init)自動建立相應目錄.

`_book` 輸出目錄[可選]

執行 gitbook build 或 gitbook serve 命令後會自動生成靜態網頁.

# 構建電子書
$ gitbook build
info: 7 plugins are installed 
info: 6 explicitly listed 
info: loading plugin "highlight"... OK 
info: loading plugin "search"... OK 
info: loading plugin "lunr"... OK 
info: loading plugin "sharing"... OK 
info: loading plugin "fontsettings"... OK 
info: loading plugin "theme-default"... OK 
info: found 5 pages 
info: found 0 asset files 
info: >> generation finished with success in 0.7s ! 

# 檢視輸出目錄
$ tree _book/
_book/
├── first
│   ├── 01.html
│   └── 02.html
├── first.html
├── gitbook
│   ├── fonts
│   │   └── fontawesome
│   │       ├── FontAwesome.otf
│   │       ├── fontawesome-webfont.eot
│   │       ├── fontawesome-webfont.svg
│   │       ├── fontawesome-webfont.ttf
│   │       ├── fontawesome-webfont.woff
│   │       └── fontawesome-webfont.woff2
│   ├── gitbook-plugin-fontsettings
│   │   ├── fontsettings.js
│   │   └── website.css
│   ├── gitbook-plugin-highlight
│   │   ├── ebook.css
│   │   └── website.css
│   ├── gitbook-plugin-lunr
│   │   ├── lunr.min.js
│   │   └── search-lunr.js
│   ├── gitbook-plugin-search
│   │   ├── lunr.min.js
│   │   ├── search-engine.js
│   │   ├── search.css
│   │   └── search.js
│   ├── gitbook-plugin-sharing
│   │   └── buttons.js
│   ├── gitbook.js
│   ├── images
│   │   ├── apple-touch-icon-precomposed-152.png
│   │   └── favicon.ico
│   ├── style.css
│   └── theme.js
├── index.html
├── search_index.json
└── second.html

10 directories, 28 files
$ 
複製程式碼

`book.json` 配置檔案[可選]

在根目錄下新建 book.json 配置檔案,完整的支援項請參考官方文件,下面僅列舉常用的一些配置項.

`title` 標題

書籍的標題

示例:

"title": "雪之夢技術驛站"
複製程式碼

`author` 作者

書籍的作者

示例:

"author": "snowdreams1006"
複製程式碼

`description` 描述

書籍的簡要描述

示例:

  "description": "雪之夢技術驛站又名snowdreams1006的技術小屋.主要分享個人的學習經驗,一家之言,僅供參考."
複製程式碼

`isbn` 國際標準書號

書籍的國際標準書號

示例:

  "isbn": "978-0-13-601970-1"
複製程式碼

選填,請參考 ISBN Search

`language` 語言

支援語言項: 預設英語(en),設定成簡體中文(zh-hans)

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"
複製程式碼

`direction` 閱讀順序

閱讀順序,支援從右到左(rtl)或從左到右(ltr),預設值取決於語言值.

示例:

"direction" : "ltr"
複製程式碼

`gitbook` 版本

指定 gitbook 版本,支援SemVer規範,接受類似於 >=3.2.3 的條件.

示例:

"gitbook": "3.2.3"
複製程式碼

`root` 根目錄

指定存放 gitbook 檔案(除了book.json檔案本身)的根目錄

示例:

"root": "."
複製程式碼

`links` 側邊欄連結

左側導航欄新增連結,支援外鏈

示例;

"links": {
    "sidebar": {
        "我的網站": "https://snowdreams1006.cn/"
    }
}
複製程式碼

`styles` 自定義樣式

自定義全域性樣式

示例:

"styles": {
    "website": "styles/website.css",
    "ebook": "styles/ebook.css",
    "pdf": "styles/pdf.css",
    "mobi": "styles/mobi.css",
    "epub": "styles/epub.css"
}
複製程式碼

`plugins` 外掛

配置額外的外掛列表,新增新外掛項後需要執行 gitbook install 安裝到當前專案.

gitbook 預設自帶5個外掛,分別是:

highlight 語法高亮外掛
search 搜尋外掛
sharing 分享外掛
font-settings 字型設定外掛
livereload 熱載入外掛

後續會介紹一些常用外掛,如需獲取更多外掛請訪問官網外掛市場

示例:

"plugins": [
    "github",
    "pageview-count",
    "mermaid-gb3",
    "-lunr", 
    "-search", 
    "search-plus",
    "splitter",
    "-sharing", 
    "sharing-plus",
    "expandable-chapters-small",
    "anchor-navigation-ex",
    "edit-link",
    "copy-code-button",
    "chart",
    "favicon-plus",
    "donate"
]
複製程式碼

`pluginsConfig` 外掛配置

安裝外掛的相應配置項,具體有哪些配置項是由外掛本身提供的,應訪問外掛官網進行查詢.

"pluginsConfig": {
    "github": {
      "url": "https://github.com/snowdreams1006/snowdreams1006.github.io"
    },
    "sharing": {
       "douban": true,
       "facebook": false,
       "google": false,
       "hatenaBookmark": false,
       "instapaper": false,
       "line": false,
       "linkedin": false,
       "messenger": false,
       "pocket": false,
       "qq": true,
       "qzone": true,
       "stumbleupon": false,
       "twitter": false,
       "viber": false,
       "vk": false,
       "weibo": true,
       "whatsapp": false,
       "all": [
           "facebook", "google", "twitter",
           "weibo", "instapaper", "linkedin",
           "pocket", "stumbleupon"
       ]
   },
   "edit-link": {
      "base": "https://github.com/snowdreams1006/snowdreams1006.github.io/blob/master",
      "label": "編輯本頁"
    },
    "chart": {
      "type": "c3"
    },
    "favicon": "/images/favicon.ico",
    "appleTouchIconPrecomposed152": "/images/apple-touch-icon-precomposed-152.png",
    "output": "_book",
    "donate": {
      "wechat": "/images/wechat.jpg",
      "alipay": "/images/alipay.jpg",
      "title": "賞",
      "button": "捐贈",
      "alipayText": "支付寶",
      "wechatText": "微信"
    }
}
複製程式碼

`structure` 目錄結構配置

指定README.md,SUMMARY.md,GLOSSARY.md 和 LANGS.md 檔名稱.

配置項	描述
`structure.readme`	`readme` 檔名(預設值是 `README.md`)
`structure.summary`	`summary` 檔名(預設值是 `SUMMARY.md`)
`structure.glossary`	`glossary` 檔名(預設值是 `GLOSSARY.md`)
`structure.languages`	`languages` 檔名(預設值是 `LANGS.md`)

`pdf` 配置

定製 pdf 輸出格式,可能需要安裝 ebook-convert 等相關外掛

配置項	描述
`pdf.pageNumbers`	新增頁碼(預設值是 `true` )
`pdf.fontSize`	字型大小(預設值是 `12` )
`pdf.fontFamily`	字型集(預設值是 `Arial` )
`pdf.paperSize`	頁面尺寸(預設值是 `a4` ),支援`a0`,`a1`,`a2`,`a3`,`a4`,`a5`,`a6`,`b0`,`b1`,`b2`,`b3`,`b4`,`b5`,`b6`,`legal`,`letter`
`pdf.margin.top`	上邊界(預設值是 `56` )
`pdf.margin.bottom`	下邊界(預設值是 `56` )
`pdf.margin.left`	左邊界(預設值是 `62` )
`pdf.margin.right`	右邊界(預設值是 `62` )

電子書封面照片 cover.jpg 和 cover_small.jpg,後續會詳細說明.

`GLOSSARY.md` 詞彙表檔案[可選]

詞彙表檔案,用於全書的專業詞彙解釋說明,比如滑鼠懸停在專業詞彙上會有相應提示.

語法格式: ## + + 專業詞彙

學習 gitbook 前最好先學習下markdown和git,你知道他們的用途嗎?

示例:

## markdown
簡潔優雅的排版語言,簡化版的 `HTML`,加強版的 `TXT`,詳情請參考 [https://snowdreams1006.github.io/markdown/](https://snowdreams1006.github.io/markdown/)

## git
分散式版本控制系統,詳情請參考 [https://snowdreams1006.github.io/git/](https://snowdreams1006.github.io/git/)
複製程式碼

`LANGS.md` 語言檔案[可選]

支援國際化編寫圖書,一種語言一個單獨子目錄,同樣地,將語言檔案放到根目錄下.

示例:

* [English](en/)
* [French](fr/)
* [Español](es/)
複製程式碼

章節小結

開發初始階段執行 gitbook init 命令按照 SUMMARY.md 檔案內容自動建立對應目錄結構,編寫各自檔案內容後執行 gitbook serve 啟動本地服務實時預覽效果.

開發到一定程度後打算髮布服務,再執行 gitbook build 輸出到 _book/ 目錄,別忘了配置 book.json 檔案,然後就可以將 _book/ 資料夾整個扔到 nginx 等靜態伺服器上,這樣就能聯網訪問你的電子書了.

是不是很簡單,後續還會有如何釋出與匯出等相關教程,今天先到這裡,下次見!

gitbook 入門教程之使用 gitbook.com 線上開發電子書
2019-04-04
Git
gitbook 入門教程之使用 gitbook-editor 編輯器開發電子書
2019-04-04
Git
gitbook 入門教程之匯出電子書
2019-04-07
Git
gitbook 入門教程之釋出電子書
2019-04-08
Git
使用Gitbook製作電子書
2014-10-21
Git
gitbook 入門教程之 gitbook 簡介
2019-03-30
Git
使用 Gitbook 打造你的電子書
2017-09-21
Git
使用GitBook平臺釋出電子書
2014-10-23
Git
gitbook 入門教程之環境要求
2019-04-01
Git
gitbook 入門教程之快速體驗
2019-04-01
Git
gitbook 入門教程之外掛介紹
2019-04-05
Git
gitbook 入門教程之前置知識
2019-03-31
Git
Gitbook離線電子書打包方案
2016-04-20
Git
gitbook 入門教程之主題外掛(初稿)
2019-04-09
Git
gitbook 入門教程之常用命令詳解
2019-04-05
Git
gitbook 入門教程之解決windows熱載入失敗問題
2019-05-08
GitWindows
gitbook 入門教程之實用外掛(新增3個外掛)
2019-04-06
Git
git 入門教程之協同開發
2019-03-24
Git
Calibre 使用教程之把合集電子書拆分成單本
2018-03-06
Java手機程式設計入門電子書開放下載 (轉)
2008-01-06
Java程式設計
HealthKit開發快速入門教程之HealthKit開發概述簡介
2015-04-29
HTML5從入門到精通電子書pdf下載
2019-03-01
HTML
HealthKit開發快速入門教程之HealthKit資料的操作
2015-04-30
【電子書獎勵計劃】特徵工程入門與實踐1
2019-08-05
特徵工程
《Flutter實戰》開源電子書
2018-12-18
Flutter
開源電子書回饋社群
2023-11-22
Python爬蟲入門【10】：電子書多執行緒爬取
2019-07-31
Python爬蟲執行緒
HTML與CSS入門經典(第7版)電子書pdf下載
2019-03-01
HTMLCSS
C語言入門經典(第4版)電子書pdf下載
2019-01-19
C語言
Java入門教程之圖書管理系統（由簡入繁）(五)
2017-03-28
Java
使用 github, gitbook, markdown 寫部落格/寫書
2016-08-08
Github
微信小程式入門教程之四：API 使用
2020-11-02
微信小程式API
分享電子書
2019-11-03
HealthKit開發快速入門教程之HealthKit的主要型別資料
2015-05-04
型別
Web開發人員應有的15本免費電子書
2011-07-05
Web
Web開發人員應有的10本免費電子書
2011-06-24
Web
Maven 教程之入門指南
2019-04-16
Maven
Grunt入門教程之（三）
2014-09-24

gitbook 入門教程之使用 gitbook-cli 開發電子書

gitbook 的一些常用命令

安裝 gitbook-cli 腳手架工具

初始化 gitbook 專案

啟動 gitbook 專案

構建 gitbook 靜態網頁

章節小結

gitbook 的目錄結構說明

README.md 首頁檔案[必須]

SUMMARY.md 概括檔案[必須]

_book 輸出目錄[可選]

book.json 配置檔案[可選]

title 標題

author 作者

description 描述

isbn 國際標準書號

language 語言

direction 閱讀順序

gitbook 版本

root 根目錄

links 側邊欄連結

styles 自定義樣式

plugins 外掛

pluginsConfig 外掛配置

structure 目錄結構配置

pdf 配置

GLOSSARY.md 詞彙表檔案[可選]

LANGS.md 語言檔案[可選]

章節小結

相關文章

`gitbook` 的一些常用命令

安裝 `gitbook-cli` 腳手架工具

初始化 `gitbook` 專案

啟動 `gitbook` 專案

構建 `gitbook` 靜態網頁

`gitbook` 的目錄結構說明

`README.md` 首頁檔案[必須]

`SUMMARY.md` 概括檔案[必須]

`_book` 輸出目錄[可選]

`book.json` 配置檔案[可選]

`title` 標題

`author` 作者

`description` 描述

`isbn` 國際標準書號

`language` 語言

`direction` 閱讀順序

`gitbook` 版本

`root` 根目錄

`links` 側邊欄連結

`styles` 自定義樣式

`plugins` 外掛

`pluginsConfig` 外掛配置

`structure` 目錄結構配置

`pdf` 配置

`GLOSSARY.md` 詞彙表檔案[可選]

`LANGS.md` 語言檔案[可選]