用 Jekyll 搭建文档系统

技术输出型公司，一套优秀的文档管理、发布系统必不可少。文档系统是内容管理系统的一种，其对可访问性要求高、单文档更新频率低、发布频率高。笔者认为，以纯静态HTML对外发布文档是个不错的选择。但是，直接写HTML文档，费时费力、不好维护。能不能将我们常用的Markdown文档，转化为HTML对外发布呢？当然可以。本文主要介绍如何利用Jekyll搭建一套文档系统。

1. Jekyll

1.1 简介

Jekyll是一个静态页面生成工具。它能够将Markdown文档转换生成HTML。Jekyll基于Ruby实现，可以通过gem命令安装。

由于Jekyll具有易用、易部署、支持Markdown的特点，很多博客都采取Jekyll方案。同时，Jekyll还可以与GitHub的个人主页集成，向GitHub提交Markdown文件，就能够直接发布，十分便捷。

1.1 项目结构

使用命令jekyll new your_project，就可以创建一个Jekyll项目。下面是常用的几个目录：

_includes

存放页面的一些基本元素，比如footer.html，head.html，head.html，script.html等，都是可以重用的页面结构。

_layouts

存放页面布局结构。比如，首页样式default.html，文档样式post.html。Markdown文档布局的结构，需要在文档的头部指定。

_posts

存放Markdown文档的目录。命名格式：year-month-day-title.md。可以任意的建目录，但不可以包含中文。

_config.yml

配置文件。可以配置，站点的基本信息，全局常量（可以在生成模板引用），URL的格式，Markdown解释引擎等。

about.md

/about/ 路径下的关于文档。

index.md。

/路径下的首页文档。

Gemfile

指定需要使用的哪些包和版本。

Gemfile.lock

记录环境中已经安装的包和版本

1.2 基本语法

由于 Jekyll 使用的是 Liquid 渲染器，将 Markdown 转换为 HTML。 Jekyll 的模板语法和 Liquid 保持一致。

Liquid基本语法：

# if 语句
{% if user != null %}
  Hello {{ user.name }}
{% endif %}

# for 循环
{% for item in array %}
  {{ item }}
{% endfor %}

# 过滤器
Hello {{ 'tobi' | upcase }}

Jekyll 常用变量：

变量	说明
site.time	当前时间, 命令的时间点）。
site.pages	所有 Pages 的清单
site.posts	一个按照时间倒叙的所有 Posts 的清单
site.related_posts	如果当前被处理的页面是一个 Post，这个变量就会包含最多10个相关的 Post。默认的情况下，相关性是低质量的，但是能被很快的计算出来。如果你需要高相关性，就要消耗更多的时间来计算。用这个命令带上选项来计算高相关性的 Post
site.categories.CATEGORY	所有的在 CATEGORY 类别下的帖子
site.tags.TAG	所有的在 TAG 标签下的帖子

Jekyll的官方文档中，对其用法，有很详细的说明。

1.3 Jekyll的Windows运行环境

第一步：安装ruby和devkit。

地址，http://rubyinstaller.org/downloads/。下载ruby和devkit，安装ruby，并将其bin目录加入系统PATH。

第一步：解压devkit，在其目录下执行命令。

1
2
ruby dk.rb init
ruby dk.rb install

第三步：设置gem源。

修改安装源，

1
gem sources --add https://gems.ruby-china.org/ --remove https://rubygems.org/

第四步：安装Jekyll。

1
2
gem install bundler
gem install jekyll

第五步：创建一个项目。

1
jekyll new document

第六步：运行项目。

1
2
cd document
bundle exec jekyll serve -P 1000

这样就在http://127.0.0.1:1000，就启动了Jekyll。可能会提示缺失包，按照提示，使用gem安装即可。

2. 构建文档系统

Jekyll 只是一个静态 HTML 的生成器。文档系统，需要考虑的不仅仅是文档的生成，还有版本管理，发布测试，负载均衡，易于编辑，快速部署等。

2.1 部署方案

上面是一个 Nginx+Jekyll 的部署方案。

文档编辑人员，将 Markdown 文件提交到内网的 SVN 机器，外部机器通过 svn co 命令拉取 SVN 服务器的文档自动部署。

由于，需要一个可测试的发布环境，在部署 Jekyll 时，需要分别在 test.docs.domain.com 和 docs.domain.com 域名下部署两套。

测试环境应该让文档编辑者，随时可以看到文档的最终转换 HTML，需要高频周期性的发布，或者利用 svn hooks 触发发布。

Jekyll 自带的 Web 服务弱，需要 Nginx 作为前端转发请求，或者直接将请求转发到 Jekyll 生成的静态网页目录 _site。

2.2 服务配置

拉取SVN Server上的 Markdown 文档，并部署 Jekyll 的 shell 脚本。测试环境和正式环境，仅仅端口和目录不一样，测试环境端口 2000，正式环境端口 1000。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
if [ -z $name ]
then
    echo "No process can be used to killed!"
    cd /docs/
    /usr/local/bin/bundle  exec /usr/local/bin/jekyll serve --watch -P 1000 &
fi.html
id=$(lsof -i:1000|tail -1|awk '"$1"!=""{print $2}')
kill -9 $id
echo "Process name=$name($id) kill!"
cd /docs/
/usr/bin/svn  co https://svn.domain.com/document/
cd /docs/
/usr/local/bin/bundle  exec /usr/local/bin/jekyll  serve  -P 1000 &

测试环境的部署脚本，可以使用 crontab 命令，添加周期任务。

Nginx的配置

# 正式环境配置
server {
        listen       80;
        server_name  docs.domain.com;		
	    location /  {
             proxy_pass http://127.0.0.1:1000;
        }
}
# 测试环境配置，测试环境还可以配置一下白名单
server {
        listen       80;
        server_name  test.docs.domain.com;		
	    location /  {
             proxy_pass http://127.0.0.1:2000;
        }
}

3. 实践建议

permalink 是 URL 的生成规则设置。在 _config.yaml 和文档的头部，都可以设置。根据URL的生产规则，如果两篇文档生成的URL相同，那么仅仅只能发布成功一篇。特别是多人合作时，一定要保证不会生成相同的文档URL。
CDN方案更佳。

本文提供的是 Nginx 作为反向代理的方案，依然具有一定的维护成本，同时，无法抵御可能的安全风险。对于，帮助文档和官网，这类静态内容的站点，还有一种更好的方案 - CDN。将静态文件直接上传到 CDN ，然后将 CDN 绑定到 docs.domain.com 即可。如何批量上传文件到七牛 CDN，请查看七牛存储批量操作 - qshell。

4. 参考

http://jekyll.com.cn/