利用 Gitbook 生成文档中心站点

Posted 2020-06-14

利用 Gitbook 生成文档中心站点

经过一个多月，Bugtags 最近上线了自己的文档站点（docs.bugtags.com），在这里你可以找到 Bugtags 集成、使用相关的绝大部分问题。

在这之前我们使用的是第三方提供的帮助中心产品服务，在他们网站后台上面编辑文档内容，建立自己的文档体系的；但是用久了发现还是用很多不爽的地方，起码是不符合我们的习惯；

比如：该产品文档是使用富文本形式编辑和存储在数据库的；而我们自己都非常喜欢于用 Markdown 格式编写文档；而数据库保存也注定无法使用 git 来进行文档的版本管理和控制；
帮助中心页面的样式只有默认的几套，尽管提供了模板设计功能，但其实也非常鸡肋，完全无法满足我们的自定制需求。基于此我们尝试寻找其他的方案解决这个问题。

我们的需求

我们首先想明白我们需要什么样的文档管理系统；

1、 使用 Markdown 来撰写文档，所谓「无 Markdown，不文档」；我们工程师都习惯于使用 Markdown 来撰写文档，甚至我司唯一不会技术的美女静静都表示：「文档怎么可以不是 Markdown 的呢！」就刚刚催稿时她还说：「必须是 Markdown 啊，不然我不收的」。

2、 生成的网站纯静态，这样才会速度快。在起初我们也想过两种方案，一是把 Markdown 文件下载到前端，在前端渲染成 html；另一种方案是在后端把所有 Markdown 生成 HTML，前端浏览时直接加载 HTML。经过考虑，还是得采取后一种。如果前一种，让每一个终端用户都要耗费资源来渲染 Markdown，实在浪费；而且速度无法保障。而后一种思路就很清晰了：首先写Markdown文档，文档写完后全部生成静态网站，这样终端用户访问的全部都是静态的 HTML 页面了。

3、 git 管理。这个应该无需多言了吧。文档的更新升级，必须要有一个强大的版本管理系统，这个非 git 莫属了。

在一系列尝试之后，我们开始采用 Gitbook 并对他进行改写，来生成起自己的文档中心站点。

Gitbook 简介

Gitbook 是一个电子书制作程序；它把组织起来的 Markdown 文件按照层次生成电子书；这个电子书的格式可以是 epub、mobi、pdf，甚至还可以是一个网站；

它的使用也是非常简单，基本上只有两步：

1. 使用gitbook init命令，会根据文件SUMMARY.md中的内容来生成书籍目录结构；

2. 使用gitbook build把书籍生成你需要的格式。

然后所有的书籍配置都可以通过根目录下的 book.json 文件来定义。
关于 Gitbook 较详细的使用方法，可以参考 Gitbook 简明教程，这个网站本身也是由 Gitbook 来生成的。

采用 Gitbook 的原因

Gitbook 与我们的需要匹配较强，有以下几点：

1. 开源。作为一个初创小企业，我们的很多项目受益于开源产品。有很多第三方的插件来推动这个产品发展；

2. Markdown 格式撰写文档；

3. 目录结构清晰；我们可以把所有的 Markdown 文档按照不同的主题归集到不同的目录层次下；

4. 生成的网页纯静态。Gitbook 是可以把所有的 Markdown 文档生成静态的 HTML 页面；

5. 由于所有的内容都是 Markdown 文件，所以就可以使用 git 来进行版本管理和控制了；

6. 在服务器上安装 Gitbook 后，定制一个 git hook 脚本，就可以在每次文档更新提交后自动生成网站；

Gitbook 不适应我们需求的地方

Gitbook 本身的理念是把 Markdown 文件组织成一本书的概念；这与我们需要做的一个网站还是有些不太一样的；所以会有很多需要改变的地方。

你看我们的网站跟任意一个 Gitbook 默认生成的站点对比，比如 Gitbook 官方的帮助文档站点 ,会发现很多不一样；具体来说，我们修改下面这些东西：

• 目录生成逻辑；
• 插件使用；
• 搜索；
• 模板样式。

目录生成逻辑

我们在Gitbook 的模板中添加了页头、页脚。页面目录的样式也不一样：这个可不只是展现形式不一样了。细心翻阅会发现，在我们的文档网站中，有一些文档并没有出现在目录里。比如有很多繁琐的常见问题；如果每一篇都要放到目录里，目录会变得很冗长。这些就得改变 Gitbook 默认的目录菜单的生成逻辑了。

我们是这么做的：在 SUMMARY.md 文件（这个文件中的内容来定义目录结构）中专门定义一个层次，这个层次名称叫做 hide-docs，类似于这个样子：

- [hide-docs]()
    - [集成 ios SDK 看不到悬浮球？](faq/ios/icon-not-found.md)
    - [用 CocoaPods 集成无法获取最新版的 SDK？](faq/ios/cocoapods-sdk-update.md)
    - [手动集成 SDK 添加 -ObjC 导致编译出错？](faq/ios/integrate-manual-build-error.md)
    - [集成 SDK 后，编译产生了很多警告？](faq/ios/integrate-build-warning.md)

这个层级下的所有文档都是不需要出现在目录下的！然而，Gitbook 照样会读取这个层次下的文档，所以我们要在生成目录的逻辑中，稍微改写：判断如果是 hide-docs 这个层级下的文档，就不生成目录。
这个就得改写 Gitbook 程序中的 website.js 文件中的 _writeTemplate 方法，我们的代码是这样：

if( !this.replacedSummary){
  this.replacedSummary = {chapters:[]};
  if( that.book.summary && that.book.summary.chapters && that.book.summary.chapters.length ){
    var chapters = that.book.summary.chapters;
    for(var i =0; i < chapters.length;i++){
      var cur = chapters[i];
      if(/hide-docs/.test(cur.title)){
          continue;
      }
      this.replacedSummary.chapters.push(cur);
    }
  }
}

然后将该方法返回对象的 summary 属性指定为我们筛选过的 replacedSummary 变量。这样再运行gitbook build，就会发现所有的 Markdown 都被生成了 HTML，然而生成的 HTML 页面中的目录不包含这些我们需要隐藏的文档。

插件禁用

Gitbook 默认启用了搜索，字体调整等 5 个插件，但是我们是不需要这些；所以需要通过在 book.json 中指定 plugins 属性为如下：

{
  "plugins":["-sharing","-livereload","-search","-fontsettings"]
}

用减号表示不启用这些插件（这种配置方法官方帮助文档居然没提）。

搜索

接下来重点的部分就是搜索了，因为 Gitbook 官方的搜索根本不支持中文搜索，所以我们禁用了它，尽管有开源的支持中文的搜索插件，但是搜索结果的展示都是非常不直观；这些都需要从模板以及搜索引擎两方面来改进。

文档搜索我们最后采用的是强大 elasticsearch 来提供全文搜索服务，并且配合修改模板来显示搜索结果。关于 elasticsearch，这是个更复杂的话题了；这里不单说，有兴趣的朋友可以搜索相关教程。

模板

由于 Gitbook 是把 Markdown 组织成一本书的概念；对一本书来说，除了封面就是目录以及目录组织起来的正文。

而我们需要的是一个文档网站，不仅需要文档内容页面，还需要其他的页面， 比如首页，搜索页面， 404 页面，可能还需要其他的页面。这时候我不禁非常怀念 jekyll 这个静态博客生成工具，它会把根目录所有的 HTML 文件找到其对应模板嵌套生成 HTML 页面。

然而 jekyll（以及我另外尝试过的 hexo）的缺陷是组织 Markdown 文档的方式都比较扁平；是通过在每一个 Markdown 文档的首部定义目录、标签来定义其逻辑层次，而其生成的物理层次则是通过文件名中的日期来定义的。这是个最大缺陷。

目前我是用了比较野蛮的方式来解决这个问题：

• 首页：Gitbook 支持多语言，并且如果定义了多语言会有一个模板页面来生成一个首页，来选择语言入口；所以我就把这个本应作为语言选择入口的页面当成我们的首页；恩，就是你现在进去看到的那个页面。
• 404 页面：自己写了一个 404，在每次重新生成网站的时候单独把这个文件拷到根目录下；感觉很傻呢……
• 搜索页面：每一个内容页都可以是搜索页；因为我是把搜索结果显示在当前页面的内容区域；这样就可以局部刷新来展示页面结果；而不需要单独做一个模板页面了。

成果

最后，我们采用了 Gitbook 符合我们需求的部分，把不适应的上面几点想方设法解决了之后，就形成了我们现在的文档中心站点。

平时发布也是非常方便；直接编写 Markdown 文件，写完提交到服务器。在服务器端设置了 git hook 钩子，每次有文档更新时，都会自动重新生成静态网站，重新生成搜索索引。你有什么关于 Bugtags 使用方面的问题，都可以先去这里查阅一下，欢迎访问哦。