Gitbook简易上手教程

约 2252 字大约 8 分钟

2021-12-21

Gitbok是一个本地写书工具，基于md语法，使用简单，易于上手。

1.1 如何使用gitbook

安装使用说明

安装：

npm install -g gitbook-cli --force

初始化目录：

mkdir gitbook && cd gitbook gitbook init

开始编辑目录：

vim summary.md

# Summary

* [前言](README.md)
* [第一章](1/README.md)
    * [1.1，基本语法](1/基本语法.md)
* [第二章](2/README.md)

重建目录

添加相应手段后，执行book sm，即可自动生成相关章节。当然也可以手动添加章节文件。

发布静态文件

gitbook build . ../../static/books/$dir

执行目录下的build.sh

输出PDF

输出为PDF文件，需要先安装gitbook pdf

$ npm install gitbook-pdf -g

然后，用下面的命令就可以生成PDF文件了。

$ gitbook pdf

如果，你已经在编写的gitbook当前目录，也可以使用相对路径。

$ gitbook pdf .

然后，你就会发现，你的目录中多了一个名为book.pdf的文件。

1.2 解决Installing GitBook的错误

我是在win10 64位系统上遇到的这个问题。

使用如下指令安装gitook：

sudo npm install -g gitbook-cli

可能会出现一个错误：

$ gitbook serve .
Installing GitBook 3.2.3
C:\Users\LIYI\AppData\Roaming\npm\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 C:\Users\LIYI\AppData\Roaming\npm\node_modules\gitbook-cli\node_modules\npm\node_modules\graceful-fs\polyfills.js:287:18
    at FSReqCallback.oncomplete (fs.js:184:5)

这个过程可能会很长，你可能需要先干别的事，过一段时间回来看，必现报错了。

我的node版本号是v14.15.5：

$ node -v
v14.15.5

有人说是由于版本太高造成的错误，降低版本就可以了。

使用nvm降低node版本

nvm与n的区别是，n是一个node模块，nvm是node之外的脚本。

下载与安装nvm：

https://github.com/coreybutler/nvm-windows/releases

nvm -v有输出，代表安装成功了。

nvm常用指令：

nvm install 10.22   // 选择安装node 版本
nvm use 14.15       // 切换使用的node版本  
nvm list            // 查看已安装的 node 版本
nvm uninstall 6.2.0 // 卸载对应的版本

解决nvm安装失败问题

听说10.22好使，使用nvm install 10.22时，出现一个错误：

Could not retrieve https://nodejs.org/dist/latest/SHASUMS256.txt.

这是由墙造成的，是下载源的问题。去nvm的安装目录：

C:\Users\LIYI\AppData\Roaming\nvm

找到一个settings.txt文件，添加最后两行：

root: C:\Users\LIYI\AppData\Roaming\nvm
path: C:\Program Files\nodejs
node_mirror:npm.taobao.org/mirrors/node/
npm_mirror:npm.taobao.org/mirrors/npm/

配置好以后，重新安装nvm install 10.22就好使了。

安装好以后就是使用use指令切换：

$ nvm use 10.22.0
Now using node v10.22.0 (64-bit)

注意，这个切换必须在管理员模式下完成。还有，node版本的切换可能会对其它程序造成负面影响。

重新安装gitbook

可以使用node -v查看降低后的版本。现在可以重装gitbook了：

npm install -g gitbook-cli --force
npm install -g gitbook --force

切换到普通指令模式下，再执行serve指令就可以了：

$ gitbook serve .
Installing GitBook 3.2.3
gitbook@3.2.3 C:\Users\LIYI\AppData\Local\Temp\tmp-19328QAP4WZytuKh5\node_modules\gitbook
...

1.4 Gitbook能不能自定义样式?

通过books.json自定义样式：

{
  "styles": {
    "website": "styles/website.css"
  },
  ...
}

style code in styles/website.css:

.copyright{
  color: white;
}

如果样式未起作用，要注意检查样式语法，还有在.bookignore文件中，不能将styles目录忽略。

::: This text is {% em %}highlighted !{% endem %} This text is {% em %}highlighted with markdown!{% endem %} This text is {% em type="green" %}highlighted in green!{% endem %} This text is {% em type="red" %}highlighted in red!{% endem %} This text is {% em color="#ff0000" %}highlighted with a custom color!{% endem %} :::

splitter 侧边栏宽度可调节

{
    "plugins": [
        "splitter"
    ]
}

page-toc-button 悬浮目录

{
    "plugins" : [ "page-toc-button" ]
}

可选配置项：

"pluginsConfig": {
        "page-toc-button": {
            "maxTocDepth": 2,
            "minTocSize": 2
       }
}

maxTocDept 标题的最大深度（2 = h1 + h2 + h3）。不支持值> 2。默认2 minTocSize 显示toc按钮的最小toc条目数。默认 2

打赏按钮 reward

这是国人铭哥开发的插件，配置：

"pluginsConfig": ['
    "reward": {
        "wechat": "http://unclealan.cn/usr/themes/seventeen/dist/images/weixin.JPG",
        "alipay": "http://unclealan.cn/usr/themes/seventeen/dist/images/alipay.JPG",
        "button": "打赏",
        "alipayText": "支付宝",
        "wechatText": "微信"
    },
]

klipse 嵌入类似IDE的功能

Klipse配置:

{
    "plugins": ["klipse"]
}

用法，在 markdown 中：

print [x + 1 for x in range(10)]

js:

1+2

auto-scroll-table 表格滚动条

{
  "plugins": ["auto-scroll-table"]
}

默认不够宽也是没有滚动条的。

click-reveal 点击显示

默认隐藏，点击可显示。

{
    "plugins": [
        "click-reveal"
    ]
}

使用方式，markdown中。

代码：

{% reveal %}
要被隐藏的内容
{% endreveal %}

效果：

::: {% reveal %} 要被隐藏的内容 {% endreveal %} :::

默认显示的文字是 Click to show , 使用text自定义显示文字。代码：

{% reveal text="点击显示" %}
要被隐藏的内容
{% endreveal %}

效果：

::: {% reveal text="点击显示" %} 要被隐藏的内容 {% endreveal %} :::

支持html语法：

<div class="click_reveal">
    <span> 点击显示html </span>
    <div><pre><code>隐藏的文字</code></pre></div>
</div>

效果：

:::

点击显示html

隐藏的文字

:::

使用npm安装单个插件

如果觉得使用gitbook install安装有点慢，可以单个下载、安装插件，例如：

npm i gitbook-plugin-insert-logo-link

1.6 如何上传图片

上传图片是在typora中，间接使用Picgo上传到图床的。

推荐使用Picgo core，而非Picgo App。后者需要在本地启动一个web server，相当于往本地一个图片上传接口提交。显然Picgo core通过进程直接调用，效果更好。

推荐Picgo core配置：

{
  "picBed": {
    "current": "githubPlus",
    "githubPlus": {
      "branch": "master",
      "customUrl": "https://cdn.jsdelivr.net/gh/rixingyike/images",
      "origin": "github",
      "path": "2021",
      "repo": "rixingyike/images",
      "token": "在github上获取"
    },
    "uploader": "githubPlus",
    "transformer": "path"
  },
  "settings": {
    "showUpdateTip": false,
    "rename": false,
    "autoRename": false,
    "uploadNotification": true
  },
  "picgoPlugins": {
    "picgo-plugin-github-plus": true,
    "picgo-plugin-super-prefix": true,
    "picgo-plugin-compress": true,
    "picgo-plugin-gitee": false,
    "picgo-plugin-gitee-uploader": false
  },
  "picgo-plugin-super-prefix": {
    "prefixFormat": "YYYYMMDDHHmmss"
  },
  "picgo-plugin-github-plus": {
    "lastSync": "2021-03-28 02:27:30"
  },
  "picgo-plugin-compress": {
    "compress": "imagemin",
    "key": null,
    "nameType": "none"
  }
}

对该配置的说明：

jsdelivr是用于cdn加速的，加速图片被用户快速访问到。
"picgo-plugin-super-prefix"这个插件是用于上传前重命名文件的，因为重名文件不允许上传，会报一个“sha不支持”的错误。使用这个插件，须确保默认配置"autoRename"为false。
上传使用"picgo-plugin-github-plus"插件，该插件在上传上优先默认上传功能及其它插件。它同时支持上传github、gitee两个图床。注意，当启用它时，需要将"picgo-plugin-gitee"和"picgo-plugin-gitee-uploader"都置为false。

1.7 在vscode中定义markodwn代码版本

有些内容是重复的，可以借助snippets功能快捷创建。共有两个配置需要完成。

现在假设我们需要一个与hugo对应的snippet，首先需要选择文件->用户片断，新建一个markdown.json文件：

{
  "new hugo post header": {
    "prefix": "hugo",
    "body": [
      "---",
      "title: $TM_FILENAME_BASE",
      "sidebar: false
createTime: $CURRENT_YEAR-$CURRENT_MONTH-$CURRENT_DATE $CURRENT_HOUR:$CURRENT_MINUTE:$CURRENT_SECOND",
      "---"
    ]
  }
}

因为vscode默认没有这个模板，不像其它c、cpp片断，单是完成这一步好不好使。还需要在用户的settings.json文件中添加：

"[markdown]": {
    "editor.formatOnSave": true,
    "editor.renderWhitespace": "all",
    "editor.quickSuggestions": {
        "other": true,
        "comments": true,
        "strings": true
    },
    "editor.acceptSuggestionOnEnter": "on"
}

版权所有

本文链接：/posts/2021/19.html

许可证：署名-非商业性 4.0 国际 (CC-BY-NC-4.0)