Please enable Javascript to view the contents

用 Jekyll 搭建文档系统

 ·  ☕ 5 分钟

技术输出型公司,一套优秀的文档管理、发布系统必不可少。文档系统是内容管理系统的一种,其对可访问性要求高、单文档更新频率低、发布频率高。笔者认为,以纯静态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. 参考


微信公众号
作者
微信公众号