GitBook使用教程
各大站長(zhǎng)平時(shí)除了寫博客外,可以使用 gitbook 將一系列的博客專欄整理成電子書出版。這樣既方便各大網(wǎng)友閱讀,還可以帶來(lái)新的離線閱讀功能。
在以前我們只能靠出版社,或者編寫 word 文檔,來(lái)實(shí)現(xiàn)。然而有了 gitbook 之后,一切都變得那么簡(jiǎn)單了。今天就為大家分享一下,如果在 Windows 系統(tǒng)上安裝 gitbook,進(jìn)行電子書的編寫和發(fā)布。
1. GitBook Editor
最簡(jiǎn)單的方式就是使用GitBook編輯器,沒有什么難度,后面的教程主要針對(duì)命令行的方式
PS:GitBook的book頁(yè)面默認(rèn)沒有download按鈕的
需要到設(shè)置中打開,打開后再次publish生效
同步GitHub
更新失敗,無(wú)法轉(zhuǎn)換成pdf/mobi/epub格式
Token
git config --global gitbook.user username git config --global gitbook.token yourtoken2. 安裝 nodejs
首先我們需要做的是安裝 Nodejs。大家可以到 Nodejs 的官網(wǎng)進(jìn)行下載。下載完成后,執(zhí)行雙擊進(jìn)行運(yùn)行安裝。安裝完成后,打開 cmd 命令行,輸入 node -v 查看安裝的 nodejs 的相關(guān)版本信息。
也可以在安裝目錄中找到 node.exe 文件,打開輸入 node -v 查看安裝的 nodejs 的相關(guān)版本信息。
3. nodejs 鏡像配置
nodejs 安裝完成后,我們就可以開始安裝 gitbook 了。但是在安裝之前,我們還需要配置一下 nodejs 插件安裝的下載鏡像地址。因?yàn)槟J(rèn)的鏡像地址是在國(guó)外,需要翻墻才可以訪問(wèn),因此我們需要設(shè)置國(guó)內(nèi)的鏡像地址。國(guó)內(nèi)的我推薦大家使用阿里巴巴的鏡像地址 http://registry.npm.taobao.org 。執(zhí)行下面的命令,進(jìn)行配置。
npm config set registry http://registry.npm.taobao.org除了上面的方法外,我們也可以在用戶主目錄下編輯 .npmrc 文件,添加一行 registry=http://registry.npm.taobao.org 保存就可以了。用戶的主目錄一般在 C:\Users\Administrator ,具體隨你的操作系統(tǒng)系統(tǒng)盤而定。
4. 全局安裝 gitbook
現(xiàn)在我們可以開始安裝全局的 gitbook 了。執(zhí)行 npm install gitbook-cli -g 命令,進(jìn)行安裝。安裝的過(guò)程中,由于需要下載安裝包,因此大家需要等待一定的時(shí)間,具體時(shí)長(zhǎng)取決于你的網(wǎng)速和硬件配置。
安裝完成后,我們可以執(zhí)行 gitbook -v 查看安裝的版本信息。
5. gitbook 常用的命令
安裝完成了后,我們就可以開始編寫內(nèi)容,進(jìn)行電子書發(fā)布了。具體的操作,大家可以參考《GitBook簡(jiǎn)明教程》進(jìn)行學(xué)習(xí)。我這里給大家推薦3種最常用的命令
gitbook init //初始化目錄文件 gitbook help //列出gitbook所有的命令 gitbook --help //輸出gitbook-cli的幫助信息 gitbook build //生成靜態(tài)網(wǎng)頁(yè) gitbook serve //生成靜態(tài)網(wǎng)頁(yè)并運(yùn)行服務(wù)器 gitbook build --gitbook=2.0.1 //生成時(shí)指定gitbook的版本, 本地沒有會(huì)先下載 gitbook ls //列出本地所有的gitbook版本 gitbook ls-remote //列出遠(yuǎn)程可用的gitbook版本 gitbook fetch 標(biāo)簽/版本號(hào) //安裝對(duì)應(yīng)的gitbook版本 gitbook update //更新到gitbook的最新版本 gitbook uninstall 2.0.1 //卸載對(duì)應(yīng)的gitbook版本 gitbook build --log=debug //指定log的級(jí)別 gitbook builid --debug //輸出錯(cuò)誤信息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-cligitbook 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:4000gitbook 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.5gitbook -V
C:\Users\AllenIverson\Desktop\gitcourse>gitbook -V CLI version: 2.3.0 GitBook version: 3.2.2gitbook 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.錯(cuò)誤提示:ebook-convert不是內(nèi)部或外部命令,原因是GitBook在生成PDF的過(guò)程中使用到calibre的轉(zhuǎn)換功能,沒有安裝calibre或安裝了calibre沒有配置環(huán)境變量都會(huì)導(dǎo)致轉(zhuǎn)換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后,轉(zhuǎn)換成功。PS:安裝calibre后需要重新啟動(dòng)命令行窗口
設(shè)置PDF輸出格式
book.json
{"gitbook": "2.x.x","title": "Go語(yǔ)言圣經(jīng)","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}} }| pdf.pageNumbers | 是否添加頁(yè)碼,默認(rèn)是true |
| pdf.fontSize | 字體大小,默認(rèn)是12 |
| pdf.fontFamily | 字體,默認(rèn)字體是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) generatedgitbook 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) generated6. calibre
下載地址
ebook-convert
C:\Users\AllenIverson\Desktop\gitcourse>ebook-convert 用法: ebook-convert.exe input_file output_file [options]轉(zhuǎn)換不同格式的電子書。input_file 表示輸入文件,output_file 表示輸出文件。這兩者作為命令行參數(shù)必須指定到最前面。輸出的電子書格式可由 output_file 的擴(kuò)展名得到。同時(shí) output_file 也可以是一種以 .EXT 為擴(kuò)展名的特殊格式。在這種情況下,輸出文件的名稱則使用輸入文件的名稱。注意:文件名不能以連字號(hào)作為開頭。如果 output_ file 不含擴(kuò)展名,那么它將被視為一個(gè)目錄并將會(huì)在該目錄下生成 HTML 格式的“開放式電子書(OEB)”。這些文件會(huì)被視為正常文件而被輸出插件所識(shí)別。在指定輸入和輸出文件后,您可以自定義特定的轉(zhuǎn)換選項(xiàng)。根據(jù)輸入和輸出文件的類型不同可用的轉(zhuǎn)換選項(xiàng)也不同。如需獲取針對(duì)輸入和輸出文件的幫助,請(qǐng)?jiān)诿钚兄休斎?-h。對(duì)于轉(zhuǎn)換系統(tǒng)的完整文檔請(qǐng)查閱 https://manual.calibre-ebook.com/conversion.html給 ebook-convert.exe 傳有空格的參數(shù)時(shí),請(qǐng)將參數(shù)包括在引號(hào)中。例如 "C:\some path with spaces"選項(xiàng):--version 顯示程序版本號(hào)并退出-h, --help 顯示此幫助信息并退出--list-recipes 列出內(nèi)建的訂閱清單名。您可以通過(guò)如下命令創(chuàng)建基于內(nèi)建訂閱清單的電子書: ebook-convert "RecipeName.recipe" output.epubebook-convert –version
C:\Users\AllenIverson\Desktop\gitcourse>ebook-convert --version ebook-convert.exe (calibre 2.81.0) Created by: Kovid Goyal <kovid@kovidgoyal.net>使用
7. GitBook 編譯,生成pdf報(bào)錯(cuò)
最近在使用 GitBook 生成靜態(tài)網(wǎng)頁(yè)和pdf文件時(shí),百度,谷歌了很久也沒有類似的解決方案,最近發(fā)現(xiàn)是版本問(wèn)題,我把我的相關(guān)經(jīng)驗(yàn)分享給大家!
在執(zhí)行 gitbook build ,gitbook serve,gitbook pdf等命令均保持。報(bào)錯(cuò)了錯(cuò)誤提示內(nèi)容如下:
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當(dāng)然也有些網(wǎng)友的報(bào)錯(cuò)內(nèi)容如下:
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這種問(wèn)題的原因是,gitbook的版本太低。大家執(zhí)行 gitbook update 命令進(jìn)行升級(jí),升級(jí)到3.2.2版本即可。
也有網(wǎng)友反映,報(bào)一下的錯(cuò):
Error: Couldn't locate plugins "baidu, donate", Run 'gitbook install' to install plugins from registry.這是提示插件沒有安裝的錯(cuò)誤。大家執(zhí)行 gitbook install 命令完成安裝即可
8.gitbook-convert
把docx、xml、html、odt文檔轉(zhuǎn)成GitBook
安裝
$ npm install gitbook-convert -g常用命令
使用
$ gitbook-convert [options] <file> [export-directory]9. 常用插件
本節(jié)內(nèi)容轉(zhuǎn)載自:Gitbook 的使用和常用插件
Gitbook 本身功能豐富,但同時(shí)可以使用插件來(lái)進(jìn)行個(gè)性化定制。Gitbook 插件 里已經(jīng)有100多個(gè)插件,可以在 book.json 文件的 plugins 和 pluginsConfig 字段添加插件及相關(guān)配置,添加后別忘了進(jìn)行安裝。
// book.json {"title": "Webpack 中文指南","description": "Webpack 是當(dāng)下最熱門的前端資源模塊化管理和打包工具,本書大部分內(nèi)容翻譯自 Webpack 官網(wǎng)。","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": "編輯本頁(yè)"},"baidu": {"token": "a9787f0ab45d5e237bab522431d0a7ec"},"sitemap": {"hostname": "http://zhaoda.net/"}} } # 安裝插件 $ gitbook install ./editlink
內(nèi)容頂部顯示 編輯本頁(yè) 鏈接。
ad
在每個(gè)頁(yè)面頂部和底部添加廣告或任何自定義內(nèi)容。
splitter
在左側(cè)目錄和右側(cè)內(nèi)容之間添加一個(gè)可以拖拽的欄,用來(lái)調(diào)整兩邊的寬度。
image-captions
抓取內(nèi)容中圖片的 alt 或 title 屬性,在圖片下面顯示標(biāo)題。
github
在右上角顯示 github 倉(cāng)庫(kù)的圖標(biāo)鏈接。
anchors
標(biāo)題帶有 github 樣式的錨點(diǎn)。
chart
使用 C3.js 圖表。
styles-sass
使用 SASS 替換 CSS。
styles-less
使用 LESS 替換 CSS。
ga
添加 Google 統(tǒng)計(jì)代碼。
disqus
添加 disqus 評(píng)論插件。
sitemap
生成站點(diǎn)地圖。
latex-codecogs
使用數(shù)學(xué)方程式。
mermaid
使用流程圖。
book-summary-scroll-position-saver
自動(dòng)保存左側(cè)目錄區(qū)域?qū)Ш綏l的位置。
sharing
默認(rèn)的分享插件。
fontsettings
默認(rèn)的字體、字號(hào)、顏色設(shè)置插件。
search
默認(rèn)搜索插件。
tbfed-pagefooter
自定義頁(yè)腳,顯示版權(quán)和最后修訂時(shí)間。
prism
基于 Prism 的代碼高亮。
atoc
插入 TOC 目錄。
ace
插入代碼高亮編輯器。
highlight
默認(rèn)的代碼高亮插件,通常會(huì)使用 prism 來(lái)替換。
github-buttons
顯示 github 倉(cāng)庫(kù)的 star 和 fork 按鈕。
sectionx
分離各個(gè)段落,并提供一個(gè)展開收起的按鈕。
mcqx
使用選擇題。
include-codeblock
通過(guò)引用文件插入代碼。
fbqx
使用填空題。
spoiler
隱藏答案,當(dāng)鼠標(biāo)劃過(guò)時(shí)才顯示。
anchor-navigation
錨點(diǎn)導(dǎo)航。
youtubex
插入 YouTube 視頻。
redirect
頁(yè)面跳轉(zhuǎn)。
expandable-chapters
收起或展開章節(jié)目錄中的父節(jié)點(diǎn)。
baidu
使用百度統(tǒng)計(jì)。
duoshuo
使用多說(shuō)評(píng)論。
jsfiddle
插入 JSFiddle 組件。
jsbin
插入 JSBin 組件。
開發(fā)插件
最好先查看別人的插件是怎么做的,然后再看官方文檔。
10. 更多GitBook教程
- GitBook 中文解說(shuō) - 2.4
- gitbook-documentation
- gitbook-documentation
總結(jié)
以上是生活随笔為你收集整理的GitBook使用教程的全部?jī)?nèi)容,希望文章能夠幫你解決所遇到的問(wèn)題。
- 上一篇: 苹果核 - 页面动态化的基础 —— Ta
- 下一篇: fatal: unable to acc