[Skill]GitBook搭建

Gitbook

Linux centos7.2安装方式

1. 安装node.js

从官网拿到文件的下载链接：

英文网址：https://nodejs.org/en/download/ 中文网址：http://nodejs.cn/download/

代码语言：javascript复制

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"

代码语言：javascript复制

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

代码语言：javascript复制

# 检查npm是否安装成功
npm -v
# npm升级到最新版本(这一步不要做, 因为使用了低版本的node)
sudo npm install npm@latest -g
# 安装GitBook
npm install -g gitbook
npm install -g gitbook-cli

接下来运行gitbook -V查看版本信息，默认会同时安装GitBook，这一步可能报错：

代码语言：javascript复制

$ 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的版本：

代码语言：javascript复制

# 也可以从https://nodejs.org/en/download/releases/下载其他版本，MAC是以.pkg为后缀的
brew install node@10
brew unlink node
brew switch node 10.22.0 #具体看你安装的版本号

解决完之后继续报错：

代码语言：javascript复制

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

这个报错不影响，直接跳过即可。

部署服务

首先初始化一本书：

代码语言：javascript复制

$ gitbook init
warn: no summary file in this book
info: create README.md
info: create SUMMARY.md
info: initialization is finished

然后执行如下命令启动服务，在http://localhost:4000/访问即可：

代码语言：javascript复制

$ 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

在左侧导航栏添加链接信息：

代码语言：javascript复制

"links" : {
    "sidebar" : {
        "Home" : "https://www.google.com/"
    }
}

3. styles

自定义页面样式，默认情况下各generator对应的css文件：

代码语言：javascript复制

"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中设置：

代码语言：javascript复制

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

4. plugins

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

代码语言：javascript复制

"plugins": [
    "disqus"
]

gitbook自带五个插件：

highlight
search
sharing
font-settings
livereload

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

代码语言：javascript复制

"plugins": [
    "-search"
]

5. pluginsConfig

配置插件的属性：

代码语言：javascript复制

"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

代码语言：javascript复制

{
    //源码目录配置
    "root":"src",
    //设置电子书语言为简体中文
    "language": "zh-hans",
    //样式文件配置
    "styles": {
        "website": "styles/website.css"
    }
}

4. package.json

代码语言：javascript复制

"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

配置：

代码语言：javascript复制

{
    "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评论：

代码语言：javascript复制

"plugins": [
    "disqus"
],
"pluginsConfig": {
    "disqus": {
        "shortName": "gitbookuse"
    }
}

2. Search Plus

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

代码语言：javascript复制

{
    "plugins": ["-lunr", "-search", "search-plus"]
}

3. Prism

使用 Prism.js 为语法添加高亮显示，需要将highlight 插件去掉。该插件自带的主题样式较少，可以再安装 prism-themes 插件，里面多提供了几种样式，具体的样式可以参考这里，在设置样式时要注意设置 css 文件名，而不是样式名。

代码语言：javascript复制

{
    "plugins": [
        "prism",
        "-highlight"
    ],
    "pluginsConfig": {
        "prism": {
            "css": [
                "prism-themes/themes/prism-base16-ateliersulphurpool.light.css"
            ]
        }
    }
}

如果需要修改背景色、字体大小等，可以在website.css定义 pre[class*="language-"]类来修改，下面是一个示例：

代码语言：javascript复制

pre[class*="language-"] {
    border: none;
    background-color: #f7f7f7;
    font-size: 1em;
    line-height: 1.2em;
}

4. Advanced Emoji

支持emoji表情：

代码语言：javascript复制

"plugins": [
    "advanced-emoji"
]

5. Github

添加github图标：

代码语言：javascript复制

"plugins": [
    "github"
],
"pluginsConfig": {
    "github": {
        "url": "https://github.com/zhangjikai"
    }
}

6. Github Buttons

添加项目在github上的star，watch，fork情况：

代码语言：javascript复制

{
    "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 行左右的位置)：

代码语言：javascript复制

editor.container.style.lineHeight = 1.25;
editor.renderer.updateFontSize();

不过上面的做法有个问题就是，每次使用gitbook install 安装新的插件之后，代码又会重置为原来的样子。另外可以在 website.css 中加入下面的 css 代码来指定 ace 字体的大小：

代码语言：javascript复制

.aceCode {
  font-size: 14px !important;
}

使用插件：

代码语言：javascript复制

"plugins": [
    "ace"
]

8. Emphasize

为文字加上底色：

代码语言：javascript复制

"plugins": [
    "emphasize"
]

9. KaTex

为了支持数学公式, 我们可以使用KaTex和MathJax插件, 官网上说Katex速度要快于MathJax：

代码语言：javascript复制

"plugins": [
    "katex"
]

10. Splitter

使侧边栏的宽度可以自由调节：

代码语言：javascript复制

"plugins": [
    "splitter"
]

11. Mermaid-gb3

支持渲染Mermaid图表：

代码语言：javascript复制

"plugins": [
    "mermaid-gb3"
]

12. 使用 PlantUML 展示 uml 图

使用 PlantUML 展示 uml 图：

代码语言：javascript复制

{
    "plugins": ["puml"]
}

使用示例：

代码语言：javascript复制

{% plantuml %}
Class Stage
    Class Timeout {
         constructor:function(cfg)
         timeout:function(ctx)
         overdue:function(ctx)
         stage: Stage
    }
    Stage <|-- Timeout
{% endplantuml %}

13. Graph

使用function-plot绘制数学函数图：

代码语言：javascript复制

{
    "plugins": [ "graph" ],
}

下面是一个示例，需要注意的是{% graph %} 块中的内容必须是合法的 JSON格式。

代码语言：javascript复制

{% 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 绘制图形。

代码语言：javascript复制

{
    "plugins": [ "chart" ],
    "pluginsConfig": {
        "chart": {
            "type": "c3"
        }
    }
}

type可以是c3或者highcharts, 默认是c3，下面是一个示例：

代码语言：javascript复制

{% 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，同时使用两个插件即可完美解决问题：

代码语言：javascript复制

plugins: [
    "expandable-chapters",
    "chapter-fold"
]

16. Donate

打赏插件：

代码语言：javascript复制

"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播放本地视频：

代码语言：javascript复制

"plugins": [ "local-video" ]

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

代码语言：javascript复制

{% 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中加入：

代码语言：javascript复制

.video-js {
    width:100%;
    height: 100%;
}

18. Simple-page-toc

自动生成本页的目录结构。另外GitBook 在处理重复的标题时有些问题，所以尽量不适用重复的标题。

代码语言：javascript复制

{
    "plugins" : [
        "simple-page-toc"
    ],
    "pluginsConfig": {
        "simple-page-toc": {
            "maxDepth": 3,
            "skipFirstH1": true
        }
    }
}

19. Copy-code-button

为代码块添加复制的按钮：

代码语言：javascript复制

{
    "plugins": ["copy-code-button"]
}

20. Include-csv

展示 csv 文件：

代码语言：javascript复制

{
    "plugins": ["include-csv"]
}

使用示例：

代码语言：javascript复制

{% includeCsv  src="./assets/csv/test.csv", useHeader="true" %} {% endincludeCsv %}

21. Klipse

集成Klipse (online code evaluator)，可以显示代码执行结果：

代码语言：javascript复制

{
    "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.

使用示例：

代码语言：javascript复制

```eval-python
print [x   1 for x in range(10)]

代码语言：javascript复制

#### 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

node.js npm git github 开源

0 人点赞