利用 Gitbook 生成文档中心站点

通过一个多月，Bugtags 最近上线了本身的文档站点：docs.bugtags.com，在这里你能够找到 Bugtags 集成、使用相关的绝大部分问题。

在这以前咱们使用的是第三方提供的帮助中心产品服务，在他们网站后台上面编辑文档内容，创建本身的文档体系的；可是用久了发现仍是用不少不爽的地方，起码是不符合咱们的习惯；

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

咱们的需求

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

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

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

三、 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，相似于这个样子：

1 2 3 4 5

- [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 方法，咱们的代码是这样：

1 2 3 4 5 6 7 8 9 10 11 12 13

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 属性为以下：

1 2 3

{ "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 使用方面的问题，均可以先去这里查阅一下，欢迎访问哦。