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

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-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 入門教程之一招徹底解決 favicon 圖標失效問題 favicon-absolute 項目

gitbook 入門教程之網站域名備案 icp 插件歡迎訪問 gitbook-plugin-icp 官網 👋

關於寫作那些事之快速上手Mermaid流程圖

原來實現釘釘自動簽到如此簡單,每天準時上下班不是夢

go 學習筆記之解讀什麼是defer延遲函數

https://yachay.unat.edu.pe/blog/index.php?comment_area=format_blog&comment_component=blog&comment_co

linux以太網驅動總結

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` 語言文件[可選]