利用 Gitbook 生成文档中心站点_html/css_WEB-ITnose
利用 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 ，甚至还可以是一个网站；
它的使用也是非常简单，基本上只有两步：
-
使用 gitbook init 命令，会根据文件 SUMMARY.md 中的内容来生成书籍目录结构；
-
使用 gitbook build 把书籍生成你需要的格式。
然后所有的书籍配置都可以通过根目录下的 book.json 文件来定义。 关于 Gitbook 较详细的使用方法，可以参考 Gitbook 简明教程 ，这个网站本身也是由 Gitbook 来生成的。
采用 Gitbook 的原因
Gitbook 与我们的需要匹配较强，有以下几点：
-
开源。作为一个初创小企业，我们的很多项目受益于开源产品。有很多第三方的插件来推动这个产品发展；
-
Markdown 格式撰写文档；
-
目录结构清晰；我们可以把所有的 Markdown 文档按照不同的主题归集到不同的目录层次下；
-
生成的网页纯静态。Gitbook 是可以把所有的 Markdown 文档生成静态的 HTML 页面；
-
由于所有的内容都是 Markdown 文件，所以就可以使用 git 来进行版本管理和控制了；
-
在服务器上安装 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 使用方面的问题，都可以先去这里查阅一下，欢迎访问哦。
上一篇： html的