艺述论

Appearance

🔰 Gitbook简易上手教程

🕒 Published at:

Gitbook简易上手教程 ​

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)
# 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
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)
$ 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
$ node -v
v14.15.5

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

使用nvm降低node版本 ​

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

下载与安装nvm：

https://github.com/coreybutler/nvm-windows/releases
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 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.
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/
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)
$ 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
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
...
$ gitbook serve .
Installing GitBook 3.2.3
gitbook@3.2.3 C:\Users\LIYI\AppData\Local\Temp\tmp-19328QAP4WZytuKh5\node_modules\gitbook
...

1.3 如何自动生成目录 ​

先全局安装一个模块：

npm install -g gitbook-summary

然后在图书目录下执行：

book sm -i _book

-i参数用于忽略目录。_book是gitbook自动生成的输出目录，它是应该被忽略的。

如果有多个目录需要忽略，可以这样设置参数：

book sm -i [_book,node_modules, styles]

如果书籍目录下有book.json文件，就是配置文件在起作用了：

{
  "ignores": ["_book","styles","node_modules"],
  ...
{
  "ignores": ["_book","styles","node_modules"],
  ...

配置文件优先级更高。

1.4 Gitbook能不能自定义样式? ​

通过books.json自定义样式：

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

style code in styles/website.css:

.copyright{
  color: white;
}
.copyright{
  color: white;
}

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

1.5 安装常用插件 ​

在book.json中可以配置插件。

GitBook 默认自带5个插件：

  • highlight： 代码高亮
  • search： 导航栏查询功能，据说默认不支持中文
  • sharing：右上角分享功能
  • font-settings：字体设置，最上方的"A"符号
  • livereload：为GitBook实时重新加载

如果要替换默认插件，需要在book.json中将默认插件使用“-”号“减”去。

这是我用到的插件及插件配置：

json
{
  ...
    "plugins": [
    "auto-scroll-table",
    "sidebar-style",
    "click-reveal",
    "-lunr",
    "-search",
    "search-pro",
    "back-to-top-button",
    "insert-logo-link",
    "chapter-fold",
    "code",
    "advanced-emoji",
    "emphasize",
    "splitter",
    "expandable-chapters-small",
    "page-toc-button",
    "klipse",
    "donate",
    "alerts"
  ],
  "pluginsConfig": {
    "sidebar-style": {
      "title": "艺术论",
      "author": "LIYI"
    },
    "donate": {
      "wechat": "images/wxpaycode.jpg",
      "alipay": "images/alipaycode.jpg",
      "title": "",
      "button": "打赏",
      "alipayText": "支付宝打赏",
      "wechatText": "微信打赏"
    },
    "page-toc-button": {
      "maxTocDepth": 2,
      "minTocSize": 2
    },
    "insert-logo-link": {
      "src": "https://yishulun.com/avatar.png",
      "url": "https://yishulun.com",
      "style": "background: none; max-height: 50px; border-radius: 50%;"
    }
  }
}
{
  ...
    "plugins": [
    "auto-scroll-table",
    "sidebar-style",
    "click-reveal",
    "-lunr",
    "-search",
    "search-pro",
    "back-to-top-button",
    "insert-logo-link",
    "chapter-fold",
    "code",
    "advanced-emoji",
    "emphasize",
    "splitter",
    "expandable-chapters-small",
    "page-toc-button",
    "klipse",
    "donate",
    "alerts"
  ],
  "pluginsConfig": {
    "sidebar-style": {
      "title": "艺术论",
      "author": "LIYI"
    },
    "donate": {
      "wechat": "images/wxpaycode.jpg",
      "alipay": "images/alipaycode.jpg",
      "title": "",
      "button": "打赏",
      "alipayText": "支付宝打赏",
      "wechatText": "微信打赏"
    },
    "page-toc-button": {
      "maxTocDepth": 2,
      "minTocSize": 2
    },
    "insert-logo-link": {
      "src": "https://yishulun.com/avatar.png",
      "url": "https://yishulun.com",
      "style": "background: none; max-height: 50px; border-radius: 50%;"
    }
  }
}

back-to-top-button 回到顶部按钮 ​

{
    "plugins": [
         "back-to-top-button"
    ]
}
{
    "plugins": [
         "back-to-top-button"
    ]
}

code 代码添加行号&复制按钮 ​

{
    "plugins" : [ "code" ]
}
{
    "plugins" : [ "code" ]
}

如果想去掉复制按钮，可配置

"pluginsConfig": {
      "code": {
        "copyButtons": false
      }
}
"pluginsConfig": {
      "code": {
        "copyButtons": false
      }
}
{
    "plugins": [ "insert-logo-link" ]
    "pluginsConfig": {
      "insert-logo": {
        "src": "https://yishulun.com",
        "url": "avator.jpg"
      }
    }
}
{
    "plugins": [ "insert-logo-link" ]
    "pluginsConfig": {
      "insert-logo": {
        "src": "https://yishulun.com",
        "url": "avator.jpg"
      }
    }
}

如果插入的图片过大，样式不匹配，可以在styles/website.css中通过样式控制。

search-pro 高级搜索 ​

在使用此插件之前，需要将默认的search和lunr 插件去掉；在搜索结果中，关键字会高亮；自带的 search 插件，关键字不会高亮

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

emphasize 为文字加上底色 ​

{
    "plugins": [
        "emphasize"
    ]
}
{
    "plugins": [
        "emphasize"
    ]
}

然后在markdown / asciidoc内容中，使用以下内容突出显示一些文本：

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

效果：

::: 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"
    ]
}
{
    "plugins": [
        "splitter"
    ]
}

page-toc-button 悬浮目录 ​

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

可选配置项：

"pluginsConfig": {
        "page-toc-button": {
            "maxTocDepth": 2,
            "minTocSize": 2
       }
}
"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"]
}
{
    "plugins": ["klipse"]
}

用法，在 markdown 中：

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

js:

1+2
1+2

auto-scroll-table 表格滚动条 ​

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

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

click-reveal 点击显示 ​

默认隐藏，点击可显示。

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

使用方式，markdown中。

代码：

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

效果：

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

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

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

效果：

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

支持html语法：

<div class="click_reveal">
    <span> 点击显示html </span>
    <div><pre><code>隐藏的文字</code></pre></div>
</div>
<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
npm i gitbook-plugin-insert-logo-link

1.6 如何上传图片 ​

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

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

推荐Picgo core配置：

json
{
  "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"
  }
}
{
  "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
date: $CURRENT_YEAR-$CURRENT_MONTH-$CURRENT_DATE $CURRENT_HOUR:$CURRENT_MINUTE:$CURRENT_SECOND",
      "---"
    ]
  }
}
{
  "new hugo post header": {
    "prefix": "hugo",
    "body": [
      "---",
      "title: $TM_FILENAME_BASE",
      "sidebar: false
date: $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"
}
"[markdown]": {
    "editor.formatOnSave": true,
    "editor.renderWhitespace": "all",
    "editor.quickSuggestions": {
        "other": true,
        "comments": true,
        "strings": true
    },
    "editor.acceptSuggestionOnEnter": "on"
}