Jekyll

用 Jekyll 作为内部技术文档库

去年在公司的产品开发团队中推行了使用 Jekyll 静态网站生成工具来写内部技术文档，大半年下来，效果还不错。

内部技术资料的共享和维护以前一直是个问题。开始用 Office Word 正正规规的写设计文档，维护成本太高了，往往是代码已经翻天覆地变化，文档里都没有反映出来，大家不愿意更新。而且查找起来也不方便。后来推行敏捷方法，不想让文档工作那么 heavy 了，于是用 wiki 来记录。Wiki 的问题是信息非常碎片化，大家很随意的添加新页面，整个 wiki 就像一个草稿本，写得很没有系统。网状的超链接导航令读者很迷茫，不知道需要的信息入口在哪儿，有些隐藏得很深的页面没有几个人知道它们的存在。Wiki 的在线编辑体验也不是那么好。

Jekyll 是个静态网站生成工具，采用 markdown 语法来写内容，根据模板生成 HTML 页面，发布到一个 web 服务器上，就可以用浏览器在线查看内容。Jekyll 通常用来做 blog 系统，但它用来做有组织的内容发布系统也是完全胜任的。我基本上就是仿照 Jekyll 官方文档的风格和结构来组织我们产品的内部技术文档库。

使用 Jekyll 优点首先是编写方便，markdown 是个轻量的标记语言，上手简单，语法易记，而且有不少编辑工具支持。即使没有渲染成 HTML，也是直接可以阅读的，比起奇奇怪怪还各自不同的 wiki 语法好写多了。

在模板做得好以及安装合适的插件后，生成的文档显示效果相当漂亮，格式效果也很丰富。而且，我们使用了 plantuml 插件，可以直接用文字的方式写UML[^1]，比起以前用其他工具画图，截图，再嵌入文档这种方式方便多了。

[^1]: 参考 PlantUML 简介, Text to UML Diagram

技术文档库的原始文件是文本格式，用 git 来做版本管理，不用担心大家同时编辑保存时会相互覆盖的问题，修改历史也很清晰。大家都是程序员，本来代码就是用 git 来管理的，文档也用 git 管理自然是很顺手的事情。使用 jekyll-post-revision 这个插件，能够在生成的页面上显示修改历史记录。

通过 jekyll-lunr-js-search 这个插件，能为站点提供全文搜索的能力，这也是相当方便的功能。

在 Windows 上安装 Jekyll

Jekyll 是用 Ruby 开发的，在 Linux 和 Mac OS X 上安装使用都很简单，在系统中有 Ruby 环境的前提下（Mac 是自带的，Linux 的各种发行版都会有安装包），照着官网上的介绍，几个命令就搞定了。但是，在 Windows 下就不是那么简单了（顺便再黑一下 Windows，不使用 Microsoft 技术的开发者都应该离开它）。

在 Windows 上装过几次 Jekyll，可以写点教程减少大家摸索的时间。大致参考这篇 Run Jekyll on Windows。

安装 Ruby

首先需要安装 Ruby 环境。从 http://rubyinstaller.org/downloads 下载 Ruby 2.0 和 DevKit，安装 Ruby，然后将 DevKit 解压到 C:/RubyDevKit，在命令行运行下面指令完成安装。

1
2
3

cd C:\RubyDevKit 
ruby dk.rb init 
ruby dk.rb install

安装 Jekyll 相关的 gem

Gem 是 Ruby 的包管理工具。在命令行执行gem install可从互联网的仓库直接下载和安装需要的包。如果需要代理，需要先设置环境变量http_proxy，如不需要则忽略第一行。其中，jekyll这个 gem 是必须安装的，其他的视乎环境、配置和使用的插件，可能需要装，可能不需要装。

set http_proxy=http://my-proxy:8080

gem install jekyll

gem install kramdown
gem install pygments
gem install nokogiri
gem install coderay
gem install wdm
gem install json

如果在安装过程中出现 SSL 错误，从这里可以找到解决方法。

使用 Jekyll

Jekyll 的相关操作都是执行jekyll命令进行。后面的基本上就是看官方文档慢慢折腾了。

制作 jekyll.exe

上面的步骤还是有点繁琐。我们公司里的都是 Java 程序员，在电脑里装个 Ruby 环境也没有其他用处。为了推广使用，简化大家的操作，做一个 portable 的 Jekyll 可执行程序会更好。

制作的步骤基本上参考这篇 Building Jekyll.exe for Windows。

首先要安装 OCRA。可能还需要安装 psych，bigdecimal 这些 gem。

1	gem install ocra

解开 jekyll 到一个临时目录：

1	gem unpack jekyll

修改bin/jekyll，在开头增加几个依赖声明：

1
2
3

require 'nokogiri'
require 'jekyll-watch'
require 'wdm'

生成 exe 文件：

1	ocra --add-all-core --gem-all bin/jekyll lib/jekyll/mime.types lib/site_template/*/ lib/site_template/*

做出来的 jekyll.exe 需要测试一下，看看各种命令是否都能正常。视乎配置和使用插件的不同，可能需要增加更多的依赖声明。以上只是我的环境的例子，不一定适用于所有场景。

最后，我知道大家都还是懒得衣来伸手饭来张口的，就提供一个编译好的 jekyll.exe 下载，支持 kramdown 和 coderay。但还是那句话：不一定符合你的环境。