Gitbook
Linux centos7.2安装方式
1. 安装node.js
从官网拿到文件的下载链接:
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
指定 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
配置:
{
"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 %}
<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