[Skill]GitBook搭建

TOMOCAT

发布于 2021-12-16 09:48:08

2.1K0

发布于 2021-12-16 09:48:08

文章被收录于专栏：懂点编程的数据分析师

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

指定 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 %}
<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

本文参与腾讯云自媒体同步曝光计划，分享自作者个人站点/博客。

原始发表：2021/9/20 下，如有侵权请联系 cloudcommunity@tencent.com 删除

node.js

本文分享自作者个人站点/博客前往查看

如有侵权，请联系 cloudcommunity@tencent.com 删除。

本文参与腾讯云自媒体同步曝光计划，欢迎热爱写作的你一起参与！

登录后参与评论

0 条评论

热度