GitBook 实践

最近在重构项目，需要调研一下帮助文档。之前项目里面用的是 gitbook 也好多年了，觉得有点丑，想找个现代化一点的哈哈哈。但是时间有限，也是一顿百度，借鉴了许多，在这里就是稍微整理一下吧！上来就找到了这个文章，看了下时间还不算太旧，里面说调研了 vuePress 和 gitbook ，我基本上也是按照这两个方向来的。

这片文章先说说 GitBook.

Base Demo

全局安装 gitbook cli 工具.

npm install gitbook-cli -g

然后检查 gitbook 有没有安装成功

gitbook -V

出现下面这样子就安装成功了

初始化书籍目录

gitbook init

README.md 是项目起来之后默认地址(/)指向的文件

SUMMARY.md 是目录

写文档

这里只粘出来目录结构和SUMMARY.md

# Summary

* [首页](README.md)
* [介绍](docs/introduct.md)
* [第一章](docs/chapter1/README.md)
  * [第一节](docs/chapter1/section1.md)

运行

gitbook serve

打开浏览器 http://localhost:4000

基本 Demo 就完事了~

其他

多语言。

gitbook 支持多语言，在根目录下加一个 LANGS.md 文件加上支持的语言就行了，可以参考Learn Git这个地址。然后这个时候进来之后就是这个页面，有点丑哈，这个插件gitbook-plugin-multilingual-index说是可以自定义多语言主页。

我没有尝试。也没有尝试能不能在页面上弄个下拉修改语言的方案，我现在就搁在左侧菜单里面了。

关于 GitBook 全文检索。

本来是因为 gitbook 画风不好看，所以才调研的帮助文档，结果在最后定好用 vuepress 之前，产品忽然间发现 vuepress 不能满足他们全文搜索的功能，所以最终方案用的还是 gitbook.然后我就下去看了一下gitbook 全文检索是怎么做的。

不管是 gitbook 默认的搜索还是增强的搜索，他们原理都一样。把这些文件整成一个大 json，然后用 jQuery 的 getJSON 去读文件，搜索，就拿上面的 demo 为例。打包之后生成了一个 search_index.json，里面的内容是这样的。

{"index":{"version":"0.5.12","fields":[{"name":"title","boost":10},{"name":"keywords","boost":15},{"name":"body","boost":1}],"ref":"url","documentStore":{"store":{"./":["首页"],"docs/introduct.html":["介绍"],"docs/chapter1/":["第一章"],"docs/chapter1/section1.html":["1","第一节"]},"length":4},"tokenStore":{"root":{"1":{"docs":{"docs/chapter1/section1.html":{"ref":"docs/chapter1/section1.html","tf":1}}},"docs":{},"首":{"docs":{},"页":{"docs":{"./":{"ref":"./","tf":11}}}},"介":{"docs":{},"绍":{"docs":{"docs/introduct.html":{"ref":"docs/introduct.html","tf":11}}}},"第":{"docs":{},"一":{"docs":{},"章":{"docs":{"docs/chapter1/":{"ref":"docs/chapter1/","tf":11}}},"节":{"docs":{"docs/chapter1/section1.html":{"ref":"docs/chapter1/section1.html","tf":10}}}}}},"length":5},"corpusTokens":["1","介绍","第一章","第一节","首页"],"pipeline":["stopWordFilter","stemmer"]},"store":{"./":{"url":"./","title":"首页","keywords":"","body":"首页\n"},"docs/introduct.html":{"url":"docs/introduct.html","title":"介绍","keywords":"","body":"介绍\n"},"docs/chapter1/":{"url":"docs/chapter1/","title":"第一章","keywords":"","body":"第一章\n"},"docs/chapter1/section1.html":{"url":"docs/chapter1/section1.html","title":"第一节","keywords":"","body":"1-1\n"}}}

然后我看了一下我们重构前项目里面这个大 json 文件有 15M 那么大

自定义配置

上面就是一个基础款，但是他基础款的东西直接拿过来好像不是很好用，比如说

搜索: 默认搜索是没有关键词高亮的，所以你可以禁用掉默认的搜索，改成 search-pro
分享: 默认的分享都是国外的一些网站，在国内不是很适用还可以增强一下你写的文档，比如说
代码复制
回到顶部
目录展开收起
隐藏指定元素

我们可以通过配置文件实现一些自定义的配置，在根目录下新建book.json，就可以自定义配置了。

我的配置是这样滴

{
  "title": "test",
  "author": "test",
  "description": "description",
  "language": "zh-hans",
  "plugins": [
    "-highlight",
    "copy-code-button",
    "search-pro",
    "-search",
    "-lunr",
    "splitter",
    "-sharing",
    "anchor-navigation-ex",
    "expandable-chapters",
    "back-to-top-button",
    "splitter",
    "hide-element"
  ],
  "pluginsConfig": {
    "anchor-navigation-ex": {
      "showLevel": false,
      "mode": "float",
      "float": {
        "floatIcon": "fa fa-navicon",
        "showLevelIcon": false,
        "level1Icon": "fa fa-hand-o-right",
        "level2Icon": "fa fa-hand-o-right",
        "level3Icon": "fa fa-hand-o-right"
      },
      "showGoTop": false
    },
    "hide-element": {
      "elements": [".gitbook-link"]
    }
  }
}

更多配置可以参考这里

一般 gitbook 的插件都是叫 'gitbook-plugin'，所以可以自行去 NPM 上找。

配置上加上插件要重新的 gitbook install.这个命令贼拉慢，所以这个时候你直接用 npm 安装即可。忘记在哪里看到说是gitbook install 是把用到的插件全都安装一遍，所以慢什么的，但是这个我装的时候没留意。

部署优化

叫这个标题不是很准确，我就是给他加了一个 package.json 方便上到服务器打包部署。我把 gitbook 依赖放到了 package.json 里面，就不用全局安装 gitbook 了。

上 package.json

{
  "name": "Test",
  "version": "1.0.0",
  "description": "description",
  "main": "index.js",
  "dependencies": {
    "gitbook-cli": "^2.3.2",
    "gitbook-plugin-anchor-navigation-ex": "^1.0.14",
    "gitbook-plugin-back-to-top-button": "^0.1.4",
    "gitbook-plugin-baidu-tongji": "^1.0.4",
    "gitbook-plugin-collapsible-menu": "^1.0.3",
    "gitbook-plugin-copy-code-button": "^0.0.2",
    "gitbook-plugin-donate": "^1.0.2",
    "gitbook-plugin-expandable-chapters": "^0.2.0",
    "gitbook-plugin-github-buttons": "^3.0.0",
    "gitbook-plugin-hide-element": "^0.0.4",
    "gitbook-plugin-page-toc-button": "^0.1.1",
    "gitbook-plugin-search-pro": "^2.0.2",
    "gitbook-plugin-splitter": "^0.0.8",
    "gitbook-plugin-tbfed-pagefooter": "^0.0.1"
  },
  "devDependencies": {},
  "scripts": {
    "start": "gitbook serve",
    "build": "gitbook build"
  },
  "repository": {
    "type": "git",
    "url": "xxxxxx"
  },
  "keywords": [
    "help"
  ],
  "author": "Xu",
  "license": "ISC"
}