利用 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 使用方面的问题,都可以先去这里查阅一下,欢迎访问哦。
相关推荐
使用Gatsby MDX生成GitBook样式的文档/教程网站
git, 使用GitBook生成的ProGit Book fork 学习 Git这是一本书的GitBook 版本,它包括: 专业版。由 Scott Chacon编写的整个专家Git书籍,并由,发布,可以以在这里。 所有内容均以 Creative Commons Attribution非...
GitBook 是一个基于 Node.js 的命令行工具,可使用 Github/Git 和 Markdown 来制作精美的电子书,GitBook 并非关于 Git 的教程。
gitbook-documentation.rar gitbook中文手册,官方下载,内容详细。https://legacy.gitbook.com/book/chrisniael/gitbook-documentation/details
包含:(Git-2.11.1-64-bit.exe/node-v4.0.0-x64.msi/GitBook.Editor.Setup.exe/gitbook 发布文档.docx) 流程说明详见:https://blog.csdn.net/ocean42234111/article/details/89022836
静态站点:GitBook默认输出该种格式,生成的静态站点可直接托管搭载Github Pages服务上; PDF:需要安装gitbook-pdf依赖; eBook:需要安装ebook-convert; 单HTML网页:支持将内容输出为单页的HTML,不过一般用...
电子书《 Nodejs区块链开发2》: : 《 Nodejs区块链开发》: : 《用Gitbook和Github轻松构建自出版平台》: : 《 sails.js官方文档多语言电子书》: : 更多Gitbooks: ://www.gitbook.com/@imfly产品特点通过使用带...
GitBook PDF生成器 文档尚未完成。 在完成文档之前,您可以查看的讨论以获取想法。 安装 npm install -g gitbook-pdfgen 安装wkhtmltopdf并将wkhtmltopdf添加到路径。 将示例项目下载到到项目路径 cd [project ...
Gitbook 文档样板 这是一个示例,说明如何创建既可以作为纯文本阅读又可以使用 Gitbook 构建的文档。 要预览为 Gitbook,请安装 gitbook ( npm install gitbook -g ) 并运行 gitbook serve ./ 从你项目的根目录。
基于gitbook 的 md转html 项目
gitbook方便编写文档,这个是支持win版本
# 刚使用github上传代码发现会自动生成reademe文件,喜出望外 # 搭建环境也是极其坎坷,好不容易搭好了,还是一个劲的失败 # 都萌生了从头开始学习如何制作gitbook了,还好网上资料太少 # 官网又慢的要命,断了...
你可以把Gitbook生成的HTML发布出来,就形成了一个简单的静态网站。Gitbook还有一个同名的平台(gitbook.io),可以发布和销售电子书,并提供了一个Markdown客户端工具(支持Mac、Windows和Linux)帮助写作。这个...
GitBook_windows客户端
基于 Gitbook 制作电子书
一个将gitbook电子书打包成android离线电子书应用的项目。 标签:Gitbook
Gitbook桌面版本下载,官网实在太慢,用迅雷也还是很慢,分享在CSDN供大家分享下载。 这个是最新的Gitbook的版本
Gitbook编辑器,使用GitBook编写电子书,方便线下编辑电子书(window下面的哦,支持windows7 or later)
documentation, GitBook和 gitbook.io的旧文档 DEPRECATION通知本书曾经是GitBook和 GitBook.com.的文档,现在文档已经被拆分:通用知识库中的帮助中心。 源是这里的 。用于GitBook格式和工具的完整文档的工具链文档...
描述UCSC Xena的教程,实时示例和方法页面欢迎使用UCSC Xena的帮助页面从下面开始或浏览我们的“如何翻页”或“常见问题解答”。 {%embed url =“ } {%embed url =“ } {%embed url =“ }