GitBook使用教程

最簡單的方式就是使用GitBook編輯器，沒有什么難度，后面的教程主要針對命令行的方式

PS：GitBook的book頁面默認沒有download按鈕的

GitBook

需要到設置中打開，打開后再次publish生效

GitBook

同步GitHub

gitbook

更新失敗，無法轉換成pdf/mobi/epub格式

gitbook

Token

git config --global gitbook.user username
git config --global gitbook.token yourtoken

token

2. 安裝 nodejs

首先我們需要做的是安裝?Nodejs。大家可以到?Nodejs?的官網進行下載。下載完成后，執行雙擊進行運行安裝。安裝完成后，打開 cmd 命令行，輸入 node -v 查看安裝的 nodejs 的相關版本信息。

也可以在安裝目錄中找到 node.exe 文件，打開輸入 node -v 查看安裝的 nodejs 的相關版本信息。

3. nodejs 鏡像配置

nodejs 安裝完成后，我們就可以開始安裝 gitbook 了。但是在安裝之前，我們還需要配置一下 nodejs 插件安裝的下載鏡像地址。因為默認的鏡像地址是在國外，需要翻墻才可以訪問，因此我們需要設置國內的鏡像地址。國內的我推薦大家使用阿里巴巴的鏡像地址?http://registry.npm.taobao.org?。執行下面的命令，進行配置。

npm config set registry http://registry.npm.taobao.org

除了上面的方法外，我們也可以在用戶主目錄下編輯 .npmrc 文件，添加一行 registry=http://registry.npm.taobao.org?保存就可以了。用戶的主目錄一般在 C:\Users\Administrator ，具體隨你的操作系統系統盤而定。

4. 全局安裝 gitbook

現在我們可以開始安裝全局的 gitbook 了。執行 npm install gitbook-cli -g 命令，進行安裝。安裝的過程中，由于需要下載安裝包，因此大家需要等待一定的時間，具體時長取決于你的網速和硬件配置。

安裝完成后，我們可以執行 gitbook -v 查看安裝的版本信息。

5. gitbook 常用的命令

安裝完成了后，我們就可以開始編寫內容，進行電子書發布了。具體的操作，大家可以參考《GitBook簡明教程》進行學習。我這里給大家推薦3種最常用的命令

gitbook init //初始化目錄文件
gitbook help //列出gitbook所有的命令
gitbook --help //輸出gitbook-cli的幫助信息
gitbook build //生成靜態網頁
gitbook serve //生成靜態網頁并運行服務器
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 //卸載對應的gitbook版本
gitbook build --log=debug //指定log的級別
gitbook builid --debug //輸出錯誤信息

gitbook

C:\Users\AllenIverson\Desktop\gitcourse>gitbookUsage: gitbook [options] [command]Commands:ls                        List versions installed locallycurrent                   Display currently activated versionls-remote                 List remote versions available for installfetch [version]           Download and install a <version>alias [folder] [version]  Set an alias named <version> pointing to <folder>uninstall [version]       Uninstall a versionupdate [tag]              Update to the latest version of GitBookhelp                      List commands for GitBook*                         run a command with a specific gitbook versionOptions:-h, --help               output usage information-v, --gitbook [version]  specify GitBook version to use-d, --debug              enable verbose error-V, --version            Display running versions of gitbook and gitbook-cli

gitbook serve

C:\Users\AllenIverson\Desktop\gitbook-test>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 3 pages
info: found 0 asset files
info: >> generation finished with success in 1.9s !Starting server ...
Serving book on http://localhost:4000

gitbook ls

C:\Users\AllenIverson\Desktop\gitcourse>gitbook ls
GitBook Versions Installed:* 3.2.2Run "gitbook update" to update to the latest version.

gitbook ls-remote

C:\Users\AllenIverson\Desktop\gitcourse>gitbook ls-remote
Available GitBook Versions:4.0.0-alpha.5, 4.0.0-alpha.4, 4.0.0-alpha.3, 4.0.0-alpha.2, 4.0.0-alpha.1, 3.2.2, 3.2.1, 3.2.0, 3.2.0-pre.1, 3.2.0-
pre.0, 3.1.1, 3.1.0, 3.0.3, 3.0.2, 3.0.1, 3.0.0, 3.0.0-pre.15, 3.0.0-pre.14, 3.0.0-pre.13, 3.0.0-pre.12, 3.0.0-pre.11, 3
.0.0-pre.10, 3.0.0-pre.9, 3.0.0-pre.8, 3.0.0-pre.7, 3.0.0-pre.6, 3.0.0-pre.5, 3.0.0-pre.4, 3.0.0-pre.3, 3.0.0-pre.2, 3.0
.0-pre.1, 2.6.7, 2.6.6, 2.6.5, 2.6.4, 2.6.3, 2.6.2, 2.6.1, 2.6.0, 2.5.2, 2.5.1, 2.5.0, 2.5.0-beta.7, 2.5.0-beta.6, 2.5.0
-beta.5, 2.5.0-beta.4, 2.5.0-beta.3, 2.5.0-beta.2, 2.5.0-beta.1, 2.4.3, 2.4.2, 2.4.1, 2.4.0, 2.3.3, 2.3.2, 2.3.1, 2.3.0,2.2.0, 2.1.0, 2.0.4, 2.0.3, 2.0.2, 2.0.1, 2.0.0, 2.0.0-beta.5, 2.0.0-beta.4, 2.0.0-beta.3, 2.0.0-beta.2, 2.0.0-beta.1,
2.0.0-alpha.9, 2.0.0-alpha.8, 2.0.0-alpha.7, 2.0.0-alpha.6, 2.0.0-alpha.5, 2.0.0-alpha.4, 2.0.0-alpha.3, 2.0.0-alpha.2,
2.0.0-alpha.1Tags:latest : 3.2.2pre : 4.0.0-alpha.5

gitbook -V

C:\Users\AllenIverson\Desktop\gitcourse>gitbook -V
CLI version: 2.3.0
GitBook version: 3.2.2

gitbook pdf

C:\Users\AllenIverson\Desktop\gitcourse>gitbook pdf
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 3 pages
info: found 0 asset filesEbookError: Error during ebook generation: 'ebook-convert' is not recognized as an internal or external command,
operable program or batch file.

錯誤提示：ebook-convert不是內部或外部命令，原因是GitBook在生成PDF的過程中使用到calibre的轉換功能，沒有安裝calibre或安裝了calibre沒有配置環境變量都會導致轉換PDF失敗

C:\Users\AllenIverson\Desktop\gitcourse>gitbook pdf
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 3 pages
info: found 2 asset files
info: >> generation finished with success in 8.6s !
info: >> 1 file(s) generated

安裝calibre后，轉換成功。PS：安裝calibre后需要重新啟動命令行窗口

設置PDF輸出格式

book.json

{"gitbook": "2.x.x","title": "Go語言圣經","description": "<The Go Programming Language>中文版","language": "zh","structure": {"readme": "preface.md"},"pluginsConfig": {"fontSettings": {"theme": "white","family": "msyh","size": 2},"plugins": ["yahei","katex","-search"]},"pdf": {"pageNumbers": true, "fontFamily": "Arial","fontSize": 12,"paperSize": "a4","margin": {"right": 62,"left": 62,"top": 56,"bottom": 56}}
}

Variable	Description
`pdf.pageNumbers`	是否添加頁碼，默認是true
`pdf.fontSize`	字體大小，默認是12
`pdf.fontFamily`	字體，默認字體是Arial)
`pdf.paperSize`	Paper size, options are?`'a0', 'a1', 'a2', 'a3', 'a4', 'a5', 'a6', 'b0', 'b1', 'b2', 'b3', 'b4', 'b5', 'b6', 'legal', 'letter'`?(default is?`a4`)
`pdf.margin.top`	Top margin (default is?`56`)
`pdf.margin.bottom`	Bottom margin (default is?`56`)
`pdf.margin.right`	Right margin (default is?`62`)
`pdf.margin.left`	Left margin (default is?`62`)

gitbook mobi

C:\Users\AllenIverson\Desktop\gitcourse>gitbook mobi
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 32 pages
info: found 34 asset files
info: >> generation finished with success in 26.0s !
info: >> 1 file(s) generated

gitbook epub

C:\Users\AllenIverson\Desktop\gitcourse>gitbook epub
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 32 pages
info: found 34 asset files
info: >> generation finished with success in 18.5s !
info: >> 1 file(s) generated

6. calibre

下載地址

calibre

ebook-convert

C:\Users\AllenIverson\Desktop\gitcourse>ebook-convert
用法: ebook-convert.exe input_file output_file [options]轉換不同格式的電子書。input_file 表示輸入文件，output_file 表示輸出文件。這兩者作為命令行參數必須指定到最前面。輸出的電子書格式可由 output_file 的擴展名得到。同時 output_file 也可以是一種以 .EXT 為擴展名的特殊格式。在這種情況下，輸出文件的名稱則使用輸入文件的名稱。注意：文件名不能以連字號作為開頭。如果 output_
file 不含擴展名，那么它將被視為一個目錄并將會在該目錄下生成 HTML 格式的“開放式電子書(OEB)”。這些文件會被視為正常文件而被輸出插件所識別。在指定輸入和輸出文件后，您可以自定義特定的轉換選項。根據輸入和輸出文件的類型不同可用的轉換選項也不同。如需獲取針對輸入和輸出文件的幫助，請在命令行中輸入 -h。對于轉換系統的完整文檔請查閱
https://manual.calibre-ebook.com/conversion.html給 ebook-convert.exe 傳有空格的參數時，請將參數包括在引號中。例如 "C:\some path with spaces"選項:--version       顯示程序版本號并退出-h, --help      顯示此幫助信息并退出--list-recipes  列出內建的訂閱清單名。您可以通過如下命令創建基于內建訂閱清單的電子書： ebook-convert "RecipeName.recipe" output.epub

ebook-convert –version

C:\Users\AllenIverson\Desktop\gitcourse>ebook-convert --version
ebook-convert.exe (calibre 2.81.0)
Created by: Kovid Goyal <kovid@kovidgoyal.net>

使用

calibre

7. GitBook 編譯，生成pdf報錯

最近在使用 GitBook 生成靜態網頁和pdf文件時，百度，谷歌了很久也沒有類似的解決方案，最近發現是版本問題，我把我的相關經驗分享給大家！

在執行 gitbook build ，gitbook serve，gitbook pdf等命令均保持。報錯了錯誤提示內容如下：

info: 10 plugins are installed
info: 9 explicitly listed
info: loading plugin "baidu"... OK
info: loading plugin "donate"... OK
info: loading plugin "sitemap"... 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 24 pages
info: found 2 asset files
warn: "options" property is deprecated, use config.get(key) instead
warn: "options.generator" property is deprecated, use "output.name" instead
error: error while generating page "README.md":TypeError: this.contentPath is not a function

當然也有些網友的報錯內容如下：

warn: "options" property is deprecated, use config.get(key) instead
warn: "page.progress" property is deprecated
warn: "sections" property is deprecated, use page.content instead
TypeError: Path must be a string. Received undefined

這種問題的原因是，gitbook的版本太低。大家執行 gitbook update 命令進行升級，升級到3.2.2版本即可。

也有網友反映，報一下的錯：

Error: Couldn't locate plugins "baidu, donate", Run 'gitbook install' to install plugins from registry.

這是提示插件沒有安裝的錯誤。大家執行 gitbook install 命令完成安裝即可

gitbook install

8.gitbook-convert

把docx、xml、html、odt文檔轉成GitBook

安裝

$ npm install gitbook-convert -g

常用命令

gitbook-convert

使用

$ gitbook-convert [options] <file> [export-directory]

gitbook-convert

9. 常用插件

本節內容轉載自：Gitbook 的使用和常用插件

Gitbook 本身功能豐富，但同時可以使用插件來進行個性化定制。Gitbook 插件?里已經有100多個插件，可以在?book.json?文件的?plugins?和?pluginsConfig?字段添加插件及相關配置，添加后別忘了進行安裝。

// book.json
{"title": "Webpack 中文指南","description": "Webpack 是當下最熱門的前端資源模塊化管理和打包工具，本書大部分內容翻譯自 Webpack 官網。","language": "zh","plugins": ["disqus","github","editlink","prism","-highlight","baidu","splitter","sitemap"],"pluginsConfig": {"disqus": {"shortName": "webpack-handbook"},"github": {"url": "https://github.com/zhaoda/webpack-handbook"},"editlink": {"base": "https://github.com/zhaoda/webpack-handbook/blob/master/content","label": "編輯本頁"},"baidu": {"token": "a9787f0ab45d5e237bab522431d0a7ec"},"sitemap": {"hostname": "http://zhaoda.net/"}}
}

# 安裝插件
$ gitbook install ./

editlink

內容頂部顯示?編輯本頁?鏈接。

在每個頁面頂部和底部添加廣告或任何自定義內容。

splitter

在左側目錄和右側內容之間添加一個可以拖拽的欄，用來調整兩邊的寬度。

image-captions

抓取內容中圖片的?alt?或?title?屬性，在圖片下面顯示標題。

github

在右上角顯示 github 倉庫的圖標鏈接。

anchors

標題帶有 github 樣式的錨點。

chart

使用 C3.js 圖表。

styles-sass

使用 SASS 替換 CSS。

styles-less

使用 LESS 替換 CSS。

ga

添加 Google 統計代碼。

disqus

添加 disqus 評論插件。

sitemap

生成站點地圖。

latex-codecogs

使用數學方程式。

mermaid

使用流程圖。

book-summary-scroll-position-saver

自動保存左側目錄區域導航條的位置。

默認的分享插件。

fontsettings

默認的字體、字號、顏色設置插件。

search

默認搜索插件。

tbfed-pagefooter

自定義頁腳，顯示版權和最后修訂時間。

prism

基于?Prism?的代碼高亮。

atoc

插入 TOC 目錄。

ace

插入代碼高亮編輯器。

highlight

默認的代碼高亮插件，通常會使用 prism 來替換。

github-buttons

顯示 github 倉庫的 star 和 fork 按鈕。

sectionx

分離各個段落，并提供一個展開收起的按鈕。

mcqx

使用選擇題。

include-codeblock

通過引用文件插入代碼。

fbqx

使用填空題。

spoiler

隱藏答案，當鼠標劃過時才顯示。

錨點導航。

youtubex

插入 YouTube 視頻。

redirect

頁面跳轉。

expandable-chapters

收起或展開章節目錄中的父節點。

baidu

使用百度統計。

duoshuo

使用多說評論。

jsfiddle

插入 JSFiddle 組件。

jsbin

插入 JSBin 組件。

開發插件

最好先查看別人的插件是怎么做的，然后再看官方文檔。

10. 更多GitBook教程

GitBook 中文解說 - 2.4
gitbook-documentation
gitbook-documentation

---------------------
作者：futurismme
來源：CSDN
原文：https://blog.csdn.net/futurismme/article/details/100579624
版權聲明：本文為作者原創文章，轉載請附上博文鏈接！
內容解析By：CSDN,CNBLOG博客文章一鍵轉載插件