Gitbook
Linux centos7.2安装方式
1. 安装node.js
从官网拿到文件的下载链接：
英文网址：https://nodejs.org/en/download/
中文网址：http://nodejs.cn/download/
wget https://npm.taobao.org/mirrors/node/v10.16.3/node-v10.16.3-linux-x64.tar.gz
tar -xvf node-v10.16.3-linux-x64.tar.gz -C /usr/local/
# 建立软链
ln -s /usr/local/node-v10.16.3-linux-x64/bin/node /usr/local/bin/
ln -s /usr/local/node-v10.16.3-linux-x64/bin/npm /usr/local/bin/
# 检查是否成功安装
node -v
2. 安装gitbook
注意如果安装gitbook-cli失败，则：
Run "npm uninstall -g gitbook" then "npm install -g gitbook-cli"
npm install -g gitbook
npm install -g gitbook-cli
ln -s /usr/local/node-v10.16.3-linux-x64/bin/gitbook /usr/local/bin/
gitbook -V
MAC安装方式
1. 安装node.js
从https://nodejs.org/en/下载并安装Nodejs，安装完后可通过终端命令node -v检验是否安装成功。
后面可能报错，所以可以直接通过brew命令下载低版本的node。
brew install node@10 echo 'export PATH="/usr/local/opt/node@10/bin:$PATH"' >> ~/.zshrc source ~/.zshrc # 查看版本及是否安装成功 node -v
2. 安装gitbook
# 检查npm是否安装成功
npm -v
# npm升级到最新版本(这一步不要做, 因为使用了低版本的node)
sudo npm install npm@latest -g
# 安装GitBook
npm install -g gitbook
npm install -g gitbook-cli
接下来运行gitbook -V查看版本信息，默认会同时安装GitBook，这一步可能报错：
$ gitbook -V
CLI version: 2.3.2
Installing GitBook 3.2.3
/usr/local/lib/node_modules/gitbook-cli/node_modules/npm/node_modules/graceful-fs/polyfills.js:287
if (cb) cb.apply(this, arguments)
^
TypeError: cb.apply is not a function
at /usr/local/lib/node_modules/gitbook-cli/node_modules/npm/node_modules/graceful-fs/polyfills.js:287:18
at FSReqCallback.oncomplete (fs.js:169:5)
解决方法是降低node的版本：
# 也可以从https://nodejs.org/en/download/releases/下载其他版本，MAC是以.pkg为后缀的
brew install node@10
brew unlink node
brew switch node 10.22.0 #具体看你安装的版本号
解决完之后继续报错：
CLI version: 2.3.2
Installing GitBook 3.2.3
xcode-select: error: tool 'xcodebuild' requires Xcode, but active developer directory '/Library/Developer/CommandLineTools' is a command line tools instance
xcode-select: error: tool 'xcodebuild' requires Xcode, but active developer directory '/Library/Developer/CommandLineTools' is a command line tools instance
SOLINK_MODULE(target) Release/.node
CXX(target) Release/obj.target/fse/fsevents.o
SOLINK_MODULE(target) Release/fse.node
xcode-select: error: tool 'xcodebuild' requires Xcode, but active developer directory '/Library/Developer/CommandLineTools' is a command line tools instance
xcode-select: error: tool 'xcodebuild' requires Xcode, but active developer directory '/Library/Developer/CommandLineTools' is a command line tools instance
SOLINK_MODULE(target) Release/.node
CXX(target) Release/obj.target/fse/fsevents.o
SOLINK_MODULE(target) Release/fse.node
这个报错不影响，直接跳过即可。
部署服务
首先初始化一本书：
$ gitbook init
warn: no summary file in this book
info: create README.md
info: create SUMMARY.md
info: initialization is finished
然后执行如下命令启动服务，在http://localhost:4000/访问即可：
$ gitbook install
$ 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 0.4s !
Starting server ...
Serving book on http://localhost:4000
配置
1.通用配置
-
title：书本标题 -
author：作者 -
description：文档描述 -
language：语言，可选的包括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 -
gitbook：使用的gitbook版本 -
root：指定存放gitbook文件的根目录，除了book.json
2. link
在左侧导航栏添加链接信息：
"links" : {
"sidebar" : {
"Home" : "https://www.google.com/"
}
}
3. styles
自定义页面样式， 默认情况下各generator对应的css文件：
"styles": {
"website": "styles/website.css",
"ebook": "styles/ebook.css",
"pdf": "styles/pdf.css",
"mobi": "styles/mobi.css",
"epub": "styles/epub.css"
}
例如使
website.css中设置：
h1 , h2{
border-bottom: 1px solid #EFEAEA;
}v
4. plugins
配置使用的插件，添加插件后需要运行gitbook install来安装新的插件：
"plugins": [
"disqus"
]
gitbook自带五个插件：
highlightsearchsharingfont-settingslivereload
如果需要去除自带插件，可以在插件名称前加-：
"plugins": [
"-search"
]
5. pluginsConfig
配置插件的属性：
"pluginsConfig": {
"fontsettings": {
"theme": "sepia",
"family": "serif",
"size": 1
}
}
6. structure
指定 Readme、Summary、Glossary 和 Languages 对应的文件名，下面是这几个文件对应变量以及默认值：
| 变量 | 含义和默认值 |
|---|---|
| structure.readme | Readme file name (defaults to README.md) |
| structure.summary | Summary file name (defaults to SUMMARY.md) |
| structure.glossary | Glossary file name (defaults to GLOSSARY.md) |
| structure.languages | Languages file name (defaults to LANGS.md) |
gitbook代码目录布局
1. 根目录
| 目录名称 | 目录描述 |
|---|---|
| src | 电子书源码文件，book.json修改"root":"src" |
| book.json | gitbook项目配置文件 |
| _book | 开发运行文件目录 |
| build | 打包执行生产的html、pdf、epub、mobi文章 |
| .gitignore | git文件忽略 |
| node_modules | 项目插件依赖包 |
| package.json | 项目配置文件，npm init生成 |
| package-lock.json | 项目依赖锁定配置文件，自动生成 |
2. src目录
| 目录名称 | 目录描述 |
|---|---|
| SUMMARY.md | 菜单模块配置 |
| README.md | 电子书简介/前言页文档 |
| GLOSSARY.md | 词汇/注释术语列表 |
| style | 项目样式文件 |
| img | 主页面图片文件 |
| about | 关于模块文件 |
| doc | 文档模块文件 |
3. book.json
{
//源码目录配置
"root":"src",
//设置电子书语言为简体中文
"language": "zh-hans",
//样式文件配置
"styles": {
"website": "styles/website.css"
}
}
4. package.json
"scripts": {
"serve": "gitbook serve",
"build": "gitbook build . ./build/dist",
"pdf": "gitbook pdf . ./build/book.pdf",
"epub": "gitbook epub . ./build/book.epub",
"mobi": "gitbook mobi . ./build/book.mobi"
}
| 运行命令 | 命令描述 |
|---|---|
| npm run serve | 项目开发运行 |
| npm run build | 电子书打包运行 |
| npm run pdf | 项目打包成pdf文件 |
| npm run epub | 项目打包成epub |
| npm run mobi | 项目打包成mobi |
主题
1. Theme-fexa
image.png
配置：
{
"root":"src",
"language": "zh-hans",
"plugins": [
"-sharing",
"-fontsettings",
"back-to-top-button",
"copy-code-button",
"katex",
"splitter",
"-lunr",
"-search",
"search-plus",
"pageview-count",
"theme-fexa",
"cuav-chapters",
"heading-anchors",
],
"variables": {
"themeFexa":{
"showHome": false,
"showNavigator": false,
"nav":[
{
"url":"www.xxx.com",
"target":"_blank",
"name": "个人主页"
}
]
}
},
"pluginsConfig": {
"theme-fexa":{
"search-placeholder":"输入关键字搜索",
"logo":"./logo.png",
"favicon": "./favicon.ico"
}
}
}
2. theme-bookstyle
[图片上传失败...(image-b67e3b-1632146036832)]
插件
1. Disqus
添加disqus评论：
"plugins": [
"disqus"
],
"pluginsConfig": {
"disqus": {
"shortName": "gitbookuse"
}
}
2. Search Plus
支持中文搜索, 需要将默认的search 和lunr插件去掉。
{
"plugins": ["-lunr", "-search", "search-plus"]
}
3. Prism
使用 Prism.js 为语法添加高亮显示，需要将highlight 插件去掉。该插件自带的主题样式较少，可以再安装 prism-themes 插件，里面多提供了几种样式，具体的样式可以参考 这里，在设置样式时要注意设置 css 文件名，而不是样式名。
{
"plugins": [
"prism",
"-highlight"
],
"pluginsConfig": {
"prism": {
"css": [
"prism-themes/themes/prism-base16-ateliersulphurpool.light.css"
]
}
}
}
如果需要修改背景色、字体大小等，可以在website.css定义 pre[class*="language-"]类来修改，下面是一个示例：
pre[class*="language-"] {
border: none;
background-color: #f7f7f7;
font-size: 1em;
line-height: 1.2em;
}
4. Advanced Emoji
支持emoji表情：
"plugins": [
"advanced-emoji"
]
5. Github
添加github图标：
"plugins": [
"github"
],
"pluginsConfig": {
"github": {
"url": "https://github.com/zhangjikai"
}
}
6. Github Buttons
添加项目在github上的star，watch，fork情况：
{
"plugins": [
"github-buttons"
],
"pluginsConfig": {
"github-buttons": {
"repo": "zhangjikai/gitbook-use",
"types": [
"star",
"watch",
"fork"
],
"size": "small"
}
}
}
7. Ace Plugin
使 GitBook 支持ace 。默认情况下，line-height 为 1，会使代码显得比较挤，而作者好像没提供修改行高的选项，如果需要修改行高，可以到 node_modules -> github-plugin-ace -> assets -> ace.js中加入下面两行代码 (30 行左右的位置)：
editor.container.style.lineHeight = 1.25;
editor.renderer.updateFontSize();
不过上面的做法有个问题就是，每次使用gitbook install 安装新的插件之后，代码又会重置为原来的样子。另外可以在 website.css 中加入下面的 css 代码来指定 ace 字体的大小：
.aceCode {
font-size: 14px !important;
}
使用插件：
"plugins": [
"ace"
]
8. Emphasize
为文字加上底色：
"plugins": [
"emphasize"
]
9. KaTex
为了支持数学公式, 我们可以使用KaTex和MathJax插件, 官网上说Katex速度要快于MathJax：
"plugins": [
"katex"
]
10. Splitter
使侧边栏的宽度可以自由调节：
"plugins": [
"splitter"
]
11. Mermaid-gb3
支持渲染Mermaid图表：
"plugins": [
"mermaid-gb3"
]
12. 使用 PlantUML 展示 uml 图
使用 PlantUML 展示 uml 图：
{
"plugins": ["puml"]
}
使用示例：
{% plantuml %}
Class Stage
Class Timeout {
+constructor:function(cfg)
+timeout:function(ctx)
+overdue:function(ctx)
+stage: Stage
}
Stage <|-- Timeout
{% endplantuml %}
13. Graph
使用function-plot绘制数学函数图：
{
"plugins": [ "graph" ],
}
下面是一个示例，需要注意的是{% graph %} 块中的内容必须是合法的 JSON格式。
{% graph %}
{
"title": "1/x * cos(1/x)",
"grid": true,
"xAxis": {
"domain": [0.01, 1]
},
"yAxis": {
"domain": [-100, 100]
},
"data": [{
"fn": "1/x * cos(1/x)",
"closed": true
}]
}
{% endgraph %}
14. Chart
使用C3.js 或者 Highcharts 绘制图形。
{
"plugins": [ "chart" ],
"pluginsConfig": {
"chart": {
"type": "c3"
}
}
}
type可以是c3或者highcharts, 默认是c3，下面是一个示例：
{% chart %}
{
"data": {
"type": "bar",
"columns": [
["data1", 30, 200, 100, 400, 150, 250],
["data2", 50, 20, 10, 40, 15, 25]
],
"axes": {
"data2": "y2"
}
},
"axis": {
"y2": {
"show": true
}
}
}
{% endchart %}
15. Expandable-chapters和chapter-fold
使左侧的章节目录可以折叠，这两个插件各自都有一些小bug，同时使用两个插件即可完美解决问题：
plugins: [
"expandable-chapters",
"chapter-fold"
]
16. Donate
打赏插件：
"plugins": [
"donate"
],
"pluginsConfig": {
"donate": {
"wechat": "https://xxx.com/resource/weixin.png",
"alipay": "https://xxx.com/resource/alipay.png",
"title": "",
"button": "赏",
"alipayText": "支付宝打赏",
"wechatText": "微信打赏"
}
}
17. Local Video
使用Video.js播放本地视频：
"plugins": [ "local-video" ]
使用示例：为了使视频可以自适应，我们指定视频的width为100%，并设置宽高比为16:9，如下面所示：
{% raw %}
{% endraw %}
另外我们还要再配置下css，即在website.css中加入：
.video-js {
width:100%;
height: 100%;
}
18. Simple-page-toc
自动生成本页的目录结构。另外GitBook 在处理重复的标题时有些问题，所以尽量不适用重复的标题。
{
"plugins" : [
"simple-page-toc"
],
"pluginsConfig": {
"simple-page-toc": {
"maxDepth": 3,
"skipFirstH1": true
}
}
}
19. Copy-code-button
为代码块添加复制的按钮：
{
"plugins": ["copy-code-button"]
}
20. Include-csv
展示 csv 文件：
{
"plugins": ["include-csv"]
}
使用示例：
{% includeCsv src="./assets/csv/test.csv", useHeader="true" %} {% endincludeCsv %}
21. Klipse
集成Klipse (online code evaluator)，可以显示代码执行结果：
{
"plugins": ["klipse"]
}
支持语言如下：
- javascript: evaluation is done with the javascript function eval and pretty printing of the result is done with pretty-format
- clojure[script]: evaluation is done with Self-Hosted Clojurescript
- ruby: evaluation is done with Opal
- C++: evaluation is done with JSCPP
- python: evaluation is done with Skulpt
- scheme: evaluation is done with BiwasScheme
- PHP: evaluation is done with Uniter
- BrainFuck
- JSX
- EcmaScript2017
- Google Charts: See Interactive Business Report with Google Charts.
使用示例：
```eval-python
print [x + 1 for x in range(10)]
#### 22. favicon
修改网站的favicon，注意：
* 图标的格式一定要是`.ico`的，直接修改图片的后缀为`.ico`是无效的
* 图标的分辨率要是32*32的
* 这个网站可在线把图片转成图标：http://www.bitbug.net/
```json
{
"plugins": ["favicon"],
"pluginsConfig": {
"favicon": {
"shortcut": "asset/img/favicon.ico",
"bookmark": "asset/img/favicon.ico",
"appleTouch": "asset/img/favicon.ico",
"appleTouchMore": {
"120x120": "asset/img/favicon.ico",
"180x180": "asset/img/favicon.ico"
}
}
}
}
Reference
[1] http://gitbook.zhangjikai.com/plugins.html
[2] https://www.jianshu.com/p/a3f2316aee77
[3] https://segmentfault.com/a/1190000019806829