gitbook基础

gitbook是一个电子书构建工具，这是它的help文档。可以在gitbook在线编写，也可以按照规范使用gitbook-cli。注意它和git没什么关系。就像java和Javascript一样。可以参考git电子书的样式。

安装gitbook

1
npm install gitbook-cli -g

创建gitbook

和vue-cli等脚手架类似，可以创建一个基础项目。

1
gitbook init project-name

构建gitbook

和hexo很像。

1
2
gitbook build
gitbook serve

gitbook配置

gitbook的配置由book.json管理，当然gitbook在线编辑是不需要配置的，都被它封装好了，因此在线编辑只会导出资源文件。下面是一个book.json的示例。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
{
    "title": "SoCube user manual",
    "language": "en",
    "plugins": [
        "livereload",
        "tabs2",
        "popup",
        "code",
        "github",
        "splitter",
        "sharing",
        "prism",
        "image-captions-extended",
        "search-plus",
        "-highlight",
        "-search"
    ],
    "pluginsConfig": {
        "github": {
            "url": "https://github.com/GCS-ZHN/SoCube"
        },
        "image-captions": {
            "caption": "_CAPTION_"
        }
    },
    "styles": {
        "website": "styles/website.css"
    }
}

gitbook插件

所有的gitbook插件，对应nodejs的包名为gitbook-plugin-XXX，例如下面是对应的package.json。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
{
  "dependencies": {
    "gitbook-plugin-code": "0.1.0",
    "gitbook-plugin-fontsettings": "2.0.0",
    "gitbook-plugin-github": "2.0.0",
    "gitbook-plugin-highlight": "2.0.3",
    "gitbook-plugin-image-captions-extended": "0.0.3",
    "gitbook-plugin-livereload": "0.0.1",
    "gitbook-plugin-popup": "0.0.1",
    "gitbook-plugin-prism": "2.4.0",
    "gitbook-plugin-search": "2.2.1",
    "gitbook-plugin-search-plus": "1.0.4-alpha-3",
    "gitbook-plugin-sharing": "1.0.2",
    "gitbook-plugin-splitter": "0.0.8",
    "gitbook-plugin-tabs2": "0.1.3"
  }
}

插件安装可以是自己手动npm安装，也可以是在book.json中写明后，执行gitbook install来安装，但是在国内速度不行，因为没用镜像。这里有大佬收藏了一些有用插件。

gitbook多语言

gitbook支持多语种配置，在LANGS.md中配置即可，每个语言放在对应的子目录，子目录名称严格符合语言缩写标准，如：zh-hans（中文简体），zh（中文繁体）,zh-tw（中文繁体）, en（英文）等。

1
2
* [中文简体](zh-hans)
* [English](en)

此时每个子目录相当于一个独立的gitbook单语种项目，样式文件（website.css）、资源文件（.gitbook/asset）等需要放到子目录。语言选择页面的语言则由book.json中的language参数设置，默认为英文。

gitbook血泪小记

  • 固定好依赖版本
  • 多语言设定时，所以的资源如css、图片等都需要放到对应语言的子目录
  • 语言zh是繁体，zh-hans才是简体
  • 发布到github page的文件夹不可以是.开头的隐藏文件夹，因此不要直接使用gitbook.com导出的资源路径，它是.gitbook/assets。