目录

    技术输出型公司,一套优秀的文档管理、发布系统必不可少。文档系统是内容管理系统的一种,其对可访问性要求高、单文档更新频率低、发布频率高。笔者认为,以纯静态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,在其目录下执行命令。
      ruby dk.rb init
      ruby dk.rb install
      
    • 第三步:设置gem源。

    修改安装源,

    gem sources --add https://gems.ruby-china.org/ --remove https://rubygems.org/
    
    • 第四步:安装Jekyll。
      gem install bundler
      gem install jekyll
      
    • 第五步:创建一个项目。
      jekyll new document
      
    • 第六步:运行项目。
      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。

    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. 参考