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

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

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-serve.gif

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)實時預覽效果.

gitbook-experience-cli-readme.png

SUMMARY.md 概括檔案[必須]

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

gitbook-experience-cli-summary.gif

_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 配置檔案,完整的支援項請參考官方文件,下面僅列舉常用的一些配置項.

gitbook-experience-cli-book-config.png

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 等靜態伺服器上,這樣就能聯網訪問你的電子書了.

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

相關文章