[Skill]GitBook搭建

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"
}

例如使<h1> <h2>标签有下边框, 可以在website.css中设置:

h1 , h2{
    border-bottom: 1px solid #EFEAEA;
}v

4. plugins

配置使用的插件,添加插件后需要运行gitbook install来安装新的插件:

"plugins": [
    "disqus"
]

gitbook自带五个插件:

  • highlight
  • search
  • sharing
  • font-settings
  • livereload

如果需要去除自带插件,可以在插件名称前加-

"plugins": [
    "-search"
]

5. pluginsConfig

配置插件的属性:

"pluginsConfig": {
    "fontsettings": {
        "theme": "sepia",
        "family": "serif",
        "size":  1
    }
}

6. structure

指定 ReadmeSummaryGlossaryLanguages 对应的文件名,下面是这几个文件对应变量以及默认值:

变量 含义和默认值
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

支持中文搜索, 需要将默认的searchlunr插件去掉。

{
    "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上的starwatchfork情况:

{
    "plugins": [
        "github-buttons"
    ],
    "pluginsConfig": {
        "github-buttons": {
            "repo": "zhangjikai/gitbook-use",
            "types": [
                "star",
                "watch",
                "fork"
            ],
            "size": "small"
        }
    }
}

7. Ace Plugin

使 GitBook 支持ace 。默认情况下,line-height1,会使代码显得比较挤,而作者好像没提供修改行高的选项,如果需要修改行高,可以到 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

为了支持数学公式, 我们可以使用KaTexMathJax插件, 官网上说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" ]

使用示例:为了使视频可以自适应,我们指定视频的width100%,并设置宽高比为16:9,如下面所示:

{% raw %}
<video id="my-video" class="video-js" controls preload="auto" width="100%"
poster="https://zhangjikai.com/resource/poster.jpg" data-setup='{"aspectRatio":"16:9"}'>
  <source src="https://zhangjikai.com/resource/demo.mp4" type='video/mp4' >
  <p class="vjs-no-js">
    To view this video please enable JavaScript, and consider upgrading to a web browser that
    <a href="http://videojs.com/html5-video-support/" target="_blank">supports HTML5 video</a>
  </p>
</video>
{% 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

©著作权归作者所有,转载或内容合作请联系作者
  • 序言:七十年代末,一起剥皮案震惊了整个滨河市,随后出现的几起案子,更是在滨河造成了极大的恐慌,老刑警刘岩,带你破解...
    沈念sama阅读 205,033评论 6 478
  • 序言:滨河连续发生了三起死亡事件,死亡现场离奇诡异,居然都是意外死亡,警方通过查阅死者的电脑和手机,发现死者居然都...
    沈念sama阅读 87,725评论 2 381
  • 文/潘晓璐 我一进店门,熙熙楼的掌柜王于贵愁眉苦脸地迎上来,“玉大人,你说我怎么就摊上这事。” “怎么了?”我有些...
    开封第一讲书人阅读 151,473评论 0 338
  • 文/不坏的土叔 我叫张陵,是天一观的道长。 经常有香客问我,道长,这世上最难降的妖魔是什么? 我笑而不...
    开封第一讲书人阅读 54,846评论 1 277
  • 正文 为了忘掉前任,我火速办了婚礼,结果婚礼上,老公的妹妹穿的比我还像新娘。我一直安慰自己,他们只是感情好,可当我...
    茶点故事阅读 63,848评论 5 368
  • 文/花漫 我一把揭开白布。 她就那样静静地躺着,像睡着了一般。 火红的嫁衣衬着肌肤如雪。 梳的纹丝不乱的头发上,一...
    开封第一讲书人阅读 48,691评论 1 282
  • 那天,我揣着相机与录音,去河边找鬼。 笑死,一个胖子当着我的面吹牛,可吹牛的内容都是我干的。 我是一名探鬼主播,决...
    沈念sama阅读 38,053评论 3 399
  • 文/苍兰香墨 我猛地睁开眼,长吁一口气:“原来是场噩梦啊……” “哼!你这毒妇竟也来了?” 一声冷哼从身侧响起,我...
    开封第一讲书人阅读 36,700评论 0 258
  • 序言:老挝万荣一对情侣失踪,失踪者是张志新(化名)和其女友刘颖,没想到半个月后,有当地人在树林里发现了一具尸体,经...
    沈念sama阅读 42,856评论 1 300
  • 正文 独居荒郊野岭守林人离奇死亡,尸身上长有42处带血的脓包…… 初始之章·张勋 以下内容为张勋视角 年9月15日...
    茶点故事阅读 35,676评论 2 323
  • 正文 我和宋清朗相恋三年,在试婚纱的时候发现自己被绿了。 大学时的朋友给我发了我未婚夫和他白月光在一起吃饭的照片。...
    茶点故事阅读 37,787评论 1 333
  • 序言:一个原本活蹦乱跳的男人离奇死亡,死状恐怖,灵堂内的尸体忽然破棺而出,到底是诈尸还是另有隐情,我是刑警宁泽,带...
    沈念sama阅读 33,430评论 4 321
  • 正文 年R本政府宣布,位于F岛的核电站,受9级特大地震影响,放射性物质发生泄漏。R本人自食恶果不足惜,却给世界环境...
    茶点故事阅读 39,034评论 3 307
  • 文/蒙蒙 一、第九天 我趴在偏房一处隐蔽的房顶上张望。 院中可真热闹,春花似锦、人声如沸。这庄子的主人今日做“春日...
    开封第一讲书人阅读 29,990评论 0 19
  • 文/苍兰香墨 我抬头看了看天上的太阳。三九已至,却和暖如春,着一层夹袄步出监牢的瞬间,已是汗流浃背。 一阵脚步声响...
    开封第一讲书人阅读 31,218评论 1 260
  • 我被黑心中介骗来泰国打工, 没想到刚下飞机就差点儿被人妖公主榨干…… 1. 我叫王不留,地道东北人。 一个月前我还...
    沈念sama阅读 45,174评论 2 352
  • 正文 我出身青楼,却偏偏与公主长得像,于是被迫代替她去往敌国和亲。 传闻我的和亲对象是个残疾皇子,可洞房花烛夜当晚...
    茶点故事阅读 42,526评论 2 343

推荐阅读更多精彩内容