19 Gitbook简易上手教程

LIYI约 2346 字大约 8 分钟

19 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)

重建目录

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

发布静态文件

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

执行目录下的build.shopen in new window

输出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.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"],
  ...

配置文件优先级更高。

1.4 Gitbook能不能自定义样式?

通过books.json自定义样式:

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

style code in styles/website.css:

.copyright{
  color: white;
}

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

1.5 安装常用插件

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

GitBook 默认自带5个插件:

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

如果要替换默认插件,需要在book.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://www.yishulun.com/avatar.png",
      "url": "https://www.yishulun.com",
      "style": "background: none; max-height: 50px; border-radius: 50%;"
    }
  }
}

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

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

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

{
    "plugins" : [ "code" ]
}

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

"pluginsConfig": {
      "code": {
        "copyButtons": false
      }
}
{
    "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"
    ]
}

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

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",
      "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"
}
Loading...