gitbook 笔记

1. gitbook 笔记

官方文档: https://toolchain.gitbook.com/

1.1. 设置 PDF 输出格式

book.json

{
  "gitbook": "2.x.x",
  "title": "Go 语言圣经",
  "description": "<The Go Programming Language > 中文版",
  "language": "zh",
  "structure": {
    "readme": "preface.md"
  },
  "pluginsConfig": {
    "fontSettings": {
      "theme": "white",
      "family": "msyh",
      "size": 2
    },
    "plugins": [
      "yahei",
      "katex",
      "-search"
    ]
  },
  "pdf": {
    "pageNumbers": true, 
    "fontFamily": "Arial",
    "fontSize": 12,
    "paperSize": "a4",
    "margin": {
      "right": 62,
      "left": 62,
      "top": 56,
      "bottom": 56
    }
  }
}

Variable	Description
pdf.pageNumbers	是否添加页码, 默认是 true
pdf.fontSize	字体大小, 默认是 12
pdf.fontFamily	字体, 默认字体是 Arial)
pdf.paperSize	Paper size, options are 'a0', 'a1', 'a2', 'a3', 'a4', 'a5', 'a6', 'b0', 'b1', 'b2', 'b3', 'b4', 'b5', 'b6', 'legal', 'letter' (default is a4)
pdf.margin.top	Top margin (default is 56)
pdf.margin.bottom	Bottom margin (default is 56)
pdf.margin.right	Right margin (default is 62)
pdf.margin.left	Left margin (default is 62)

1.2. GitBook 插件

1.2.1. GitBook 插件资源

官网: https://plugins.gitbook.com

在里面可以搜索各种 GitBook 插件。

1.2.2. 使用 GitBook 插件

这里使用 GitBook 的 mermaid 插件举例。

1. 获知相关插件

因为我要画一个流程图, 从网上查询可知我需要一个 mermaid 插件, 搜索到其官网: https://plugins.gitbook.com/plugin/mermaid

2. 在 GitBook 目录下新建一个配置文件 book.json:

{
    "plugins": ["mermaid"]
}

3. 安装 mermaid 插件

根据上面的文档, 首先要安装:

npm install gitbook-plugin-mermaid

或者等待上面 book.json 编辑完成后, 使用自动安装命令(推荐):

gitbook install

4. 安装 calibre

由于我们需要生成 pdf 文件, 所以非常需要这个软件, 按照其 官网方法 进行安装:

sudo -v && wget -nv -O- https://download.calibre-ebook.com/linux-installer.sh | sudo sh /dev/stdin

5. 在 markdown 文档中使用 mermaid

{% mermaid %}
graph TD;
  A-->B;
  A-->C;
  B-->D;
  C-->D;
{% endmermaid %}

需要注意的是, 使用 gitbook-editor 实时浏览是不会加载插件的, 也就是说不能即时看到 mermaid 的效果, 需要 gitbook serve 命令来查看, 或者直接生成, 才能看到 mermaid 的效果。

可能用到的命令:

gitbook serve --lrport 35288 --port 4001
gitbook pdf ./ ./mybook.pdf

1.2.3. 开发插件

最好先查看别人的插件是怎么做的, 然后再看 官方文档。

1.2.4. 常用插件

• 流程图插件 plantuml
• 流程图插件 mermaid

1.2.5. 其它插件

插件名	作用
chart	使用 C3.js 图表。
latex-codecogs	使用数学方程式。
mermaid	使用流程图。
include-codeblock	通过引用文件插入代码。
styles-sass	使用 SASS 替换 CSS。
styles-less	使用 LESS 替换 CSS。
fontsettings	默认的字体、字号、颜色设置插件。
prism	基于 Prism 的代码高亮
ace	插入代码高亮编辑器。
highlight	默认的代码高亮插件, 通常会使用 prism 来替换。
mcqx	使用选择题。
fbqx	使用填空题。
spoiler	隐藏答案, 当鼠标划过时才显示。
search	默认搜索插件。
anchor-navigation	锚点导航。
book-summary-scroll-position-saver	自动保存左侧目录区域导航条的位置。
atoc	插入 TOC 目录。
redirect	页面跳转。
expandable-chapters	收起或展开章节目录中的父节点。
sectionx	分离各个段落, 并提供一个展开收起的按钮。
tbfed-pagefooter	自定义页脚, 显示版权和最后修订时间。
editlink	内容顶部显示 “编辑本页” 链接。
ad	在每个页面顶部和底部添加广告或任何自定义内容。
splitter	在左侧目录和右侧内容之间添加一个可以拖拽的栏, 用来调整两边的宽度。
image-captions	抓取内容中图片的 alt 或 title 属性, 在图片下面显示标题。
baidu	使用百度统计。
ga	添加 Google 统计代码。
sitemap	生成站点地图。
github-buttons	显示 github 仓库的 star 和 fork 按钮。
github	在右上角显示 github 仓库的图标链接。
anchors	标题带有 github 样式的锚点。
disqus	添加 disqus 评论插件。
duoshuo	使用多说评论。
youtubex	插入 YouTube 视频。
sharing	默认的分享插件。
jsfiddle	插入 JSFiddle 组件。
jsbin	插入 JSBin 组件。

1.3. 安装 GitBook

参考自: https://toolchain.gitbook.com/setup.html, 有添加。

1. 首先安装 Node.js

安装 Node.js 完成后, 再升级最新版的 npm:

npm i npm@latest -g

2. 安装 GitBook 命令行

npm install gitbook-cli -g

3. 初始化 GitBook

gitbook --version

这个命令会安装最新版本的 GitBook, 如果遇到错误:

Error: Cannot find module 'config-chain'

安装该模块即可:

npm install -g config-chain

4. 安装模块 calibre-ebook(可选)

我们可能会用到 GitBook 转换成电子书的功能, 所以需要安装模块 calibre-ebook:

Binary install:

sudo -v && wget -nv -O- https://download.calibre-ebook.com/linux-installer.py | sudo python -c "import sys; main=lambda:sys.stderr.write('Download failed\n'); exec(sys.stdin.read()); main()"

或者

sudo -v && wget -nv -O- https://download.calibre-ebook.com/linux-installer.sh | sudo sh /dev/stdin

如果没有安装模块 calibre-ebook, 会报错误:

InstallRequiredError: "ebook-convert" is not installed

1.4. 使用 GitBook

1.4.1. 初始化电子书目录

创建一个电子书的文件夹, 进入此文件夹:

$ gitbook init

执行完后, 你会看到多了两个文件—— README.md 和 SUMMARY.md, 它们的作用如下:

README.md  —— 书籍的介绍写在这个文件里
SUMMARY.md —— 书籍的目录结构在这里配置

1.4.2. 小试 GitBook 目录结构

编辑 SUMMARY.md 文件, 内容修改为:

# 目录

* [前言](README.md)
* [第一章](Chapter1/README.md)
  * [第 1 节: 衣](Chapter1 / 衣。md)
  * [第 2 节: 食](Chapter1 / 食。md)
  * [第 3 节: 住](Chapter1 / 住。md)
  * [第 4 节: 行](Chapter1 / 行。md)
* [第二章](Chapter2/README.md)
* [第三章](Chapter3/README.md)
* [第四章](Chapter4/README.md)

然后我们回到命令行, 在 mybook 文件夹中再次执行 gitbook init 命令。GitBook 会查找 SUMMARY.md 文件中描述的目录和文件, 如果没有则会将其创建。

1.5. GitBook 命令

• 构建书籍 (默认将生成的静态网站输出到 _book 目录): $ gitbook build [书籍路径] [输出路径]
• 显示网页: $ gitbook serve --port 2333
• 生成 PDF 格式的电子书: $ gitbook pdf ./ ./mybook.pdf
• 生成 epub 格式的电子书: $ gitbook epub ./ ./mybook.epub
• 生成 mobi 格式的电子书: $ gitbook mobi ./ ./mybook.mobi

gitbook init // 初始化目录文件
gitbook help // 列出 gitbook 所有的命令
gitbook --help // 输出 gitbook-cli 的帮助信息
gitbook build // 生成静态网页
gitbook serve // 生成静态网页并运行服务器
gitbook build --gitbook=2.0.1 // 生成时指定 gitbook 的版本, 本地没有会先下载
gitbook ls // 列出本地所有的 gitbook 版本
gitbook ls-remote // 列出远程可用的 gitbook 版本
gitbook fetch 标签 / 版本号 // 安装对应的 gitbook 版本
gitbook update // 更新到 gitbook 的最新版本
gitbook uninstall 2.0.1 // 卸载对应的 gitbook 版本
gitbook build --log=debug // 指定 log 的级别
gitbook builid --debug // 输出错误信息

1.6. 开多个 GitBook 服务

gitbook 启动的 web 服务默认监听 4000 端口, 而重启监控进程默认监听 35729 端口。一般这样可以启动一个电子书 web 服务:

gitbook serve /somepath/your_docuemtn_dir/

本地就可以这样来访问: http://localhost:4000

如果要启动另一部电子书服务的话, 就需要同时修改 web 端口和监控进程端口, 类似这样:

gitbook serve --lrport 35288 --port 4001 /path2/your_another_doc_dir/

否则就会产生端口已被占用的情况。

1.7. 版本管理

除此之外, 别忘了还可以用 Git 做版本管理呀! 在 mybook 目录下执行 git init 初始化仓库, 执行 git remote add 添加远程仓库 (你得先在远端建好)。接着就可以愉快地 commit, push, pull … 啦!