简介：本文主要介绍利用jekyll在github上搭建站点的方法与原理。
##jekyll与github的关系
github站点是位于username.github.com仓库中的静态页面。利用高效的工具生成高质量的静态页面是github建站的王道。jekyll就是用ruby制造静态站点的的ruby解析引擎（构建网站时ruby不是必会的）。github除了能构建独立的站点外，还可以为每个项目建立站点。github提供了自动和手动建立项目站点的方法。
github标配有jekyll解析引擎，上传的站点可以代由github的jekyll解析为静态页面。如果不需要github用jekyll处理上传的站点文件，可以在根目录下添加一个.nojekyll文件。
github使用jekyll的_config.yml和用户本地jekyll的不同，它的功能有限，github运行jekyll带有--safe参数。如果用户本地的jekyll使用了自定义插件，github的解析会出错，启用了本地自定义插件的用户可以上传本地解析好的静态页面到github。
由于本地和gihub的jekyll版本不同，即使本地正常解析的页面也可能会在github上解析出错。下面的表格在github上Jekyll 0.11.0 with Liquid 2.2.2会出错：
功能 | 快捷键 | 快捷键 | 功能
-------: | -------: | :------- | :-------
上一节点 | `p` | `n` | 下一节点
|| `m` | 菜单 ##jekyll驱动网站原理
用jekyll构建静态网站很容易。模板、数据和美化是jekyll建站的三要素。jekyll自动将数据注入模板，通过美化，得到站点。这里可以看到一堆用jekyll打造的站点，大部分都可以git clone回来学习参考。
###jekyll的模板
jekyll模板就是带有变量的html格式文件。jekyll的模板用Liquid语言描述，定义了页面框架。Liquid通过（Output）和标签（Tag）两种标记（markup），即可描述页面的结构，具体可参阅Liquid for Designers。jekyll对Liquid的标签进行了扩展。Liquid模板语言对模板数据描述（当然也需要html），生成了站点页面的骨架。Liquid所需要的jekyll的模板数据在这儿可以找到。除此之外，YAML Front Matter定义的变量也可以作为模板数据。
###jekyll的数据
jekyll的数据是用markdown、textile等标记语言写的文档。这些格式的文档解析为html格式后，注入jekyll模板的{{ content }}，就有了网站的页面。jekyll支持的markdown解析器（将markdown转换为html）有：rdiscount、kramdown、redcarpet、maruku（jekyll默认）、bluecloth。为了方便处理公式，也有人hack了jekyll，将pandoc作为markdown的解析器。一个更方便的方法是通过jekyll-pandoc-plugin插件，启用pandoc解析器。这些hack后的jekyll启用pandoc当然不会在github上生效，只能用于本机解析后，上传静态页面。
###jekyll的美化
美化就是用CSS和javascript对html描述的页面进行渲染，美化网页。twitter bootstrap是一套极易上手的页面美化工具。twitter bootstrap还提供了960网格布局，只要按照它约定的方式对页面结构定义、对html标签的class命名，网页的布局美化可谓快又好。
##在jekyll-bootstrap基础上搭建网站
jekyll是一套根据相应规程生成网站的工具。如果按照这套法则，从头开始仍然麻烦。jekyll-bootstrap就是一个jekyll构建站点的demo，并提供了一些额外的api增强jekyll的功能，在此基础上构建站点相当快捷容易。除此之外，octopress也是基于jekyll上的不错的工具套件。
###目录结构
jekyll-bootstrap的目录结构中，只需要将markdown文档放到_posts目录下，jekyll --server（新版采用jekyll serve命令），即可在http://localhost:4000看到页面内容，见快速入门示范。_posts中的数据文档，通过注入_layouts定义的模板（_layouts的模板一般指向了_includes/themes中的模板），渲染页面的CSS和JS文档在assets/themes中，一些解析markdown用到的ruby插件放在_plugins目录。通过jekyll --server（新版采用jekyll serve命令）最终生成的静态页面在_sites目录。在更新github上站点的时候，git push可以不必推送_sites目录，将页面的解析留给github，这样做的前提条件是本地未启用自定义插件，_config.yml设置safe = true进行解析。如果本地启用了自定义插件，解析任务就不能交给github做了，上传本地解析好的静态页面到github即可。
jekyll-bootstrap的_includes/JB中有一些常用的工具，用于列表显示、评论等，可参看_includes/themes中主题的相关html文档学习。
_includes/themes中的主题一般包含default.html、post.html和page.html三个文档。default.html定义了网站的最上层框架（模板），post.html和page.html是其子框架（模板）。post和page有别；rake page命令生成的页面按page.html解析，markdown文件的YAML Front Matter中layout: page；rake post命令生成的页面按post.html解析，markdown文件的YAML Front Matter中layout: post。生成好的html子页面通过default.html的{{ content }}变量调用，生成整个页面。
###自定义
站点生成需要用到_config.yml配置文件，markdown变量定义了解析markdown用的解析器。当然也可自定义变量，比如在JB:下定义一个二级变量RSS_path: /atom.xml（注意缩进）。在html页面中，就可以用{{ site.JB.RSS_path }}得其值。YAML Front Matter中也可以自定义变量，其中的title变量可以用{{ page.title }}访问到。也就是说，站点的全局变量在_config.yml中定义，用site.访问，页面的变量在YAML Front Matter中定义，用page.访问，更多的模板变量可参考模板数据。
_includes/JB中的插件可以在_includes/custom中重新自定义，方法可仿照_includes/JB中的。如果要_includes/custom中的插件生效，需要在_config.yml中将相应的变量设为custom，设置线索可见_includes/JB中的插件。
###小结
jekyll生成静态页面的过程就是先搜集站点的原始数据，通过计算，生成用于页面显示的结构化数据（最终的html静态页面）。结构化数据来源有两方面：一方面是文件中的配置文件，如_config.yml和markdown的YAML Front Matter；另一方面通过目录结构和jekyll定义的解析法则，产生数据。站点的全局数据用site.访问，页面数据用page.访问。有了这些结构化的数据后，jekyll再按照用户定义的模板，用相应的结构化数据替换模板中的变量。用户编写的插件是为了计算出满足用户特定需求的数据，但是这些自定义插件不能不github的jekyll解析支持。
##jekyll的装饰部件
这些装饰部件中，如果本地的jekyll使用了自定义的插件，github的jeklly解析器不会支持这些自定义插件。
###图片与文件
站点需要的图片直接存放在assets/images文件夹中，可以在_config.yml中定义一个形如img_url: http://jiyeqian.github.com/assets/images的变量，然后在markdown文件需要用到图片的地方插入类似的代码即可显示图像。
如果图和文件较多，这里有一些图片和文件托管的网络资源供参考。
###代码高亮
网页代码高亮的一般原理是先用JS或其它脚本语言对代码的进行解析，并提根据不同程的序语言提取关键字、变量、常量、注释，然后将代码层次结构用html标签描述，最后用CSS着色。
代码高亮的方案有很多，比如：转帖gist代码的插件，google-code-prettify，利用pygments高亮代码的插件，octopress的backtick-codeblock，如果需要在线展示html、js、CSS及其效果，当然还是用jsfiddle插件。
pygments和rouge是github可支持的代码高亮方案(不支持coderay高亮)。利用pygments，须先在_config.yml中设置pygments: true，并嵌入生成的相应CSS到页面的<head></head>之中。
$ pygmentize -S default -f html | sed 's/^/.highlight code /g' > default.css在pygments的CSS选择器前都加上.highlight code，防止pygments的CSS影响mathjax公式的CSS。pygments也可能会和bootstrap.min.css冲突，需要修改css。上面的pygmentize命令就是pygments代码高亮的效果。代码高亮的highlight标签使用方法可以参考这里。
另一个比较特殊的代码高亮插件是include-code，可以直接显示目录中的代码文件，在_config.yml中设置好code_dir参数后，直接用{% include_code excerpt.rb %}，即可显示高亮代码（布局可自己定义，代码高亮的CSS可以用pygments的）。pygments也支持类似的方法，但效果不太好。
###公式
github可支持的方案需要绕过自定义插件，利用类似mathjax的javascript方案或采用支持的markdown解析器（比如maruku）。
mathjax通过javascript的方式生成公式可以参考在Octopress中使用，不过，不必把markdown解析引擎设置为kramdown。当markdown解析引擎为kramdown时，只需要在页面中插入下面这段代码：
<script type="text/javascript" src="http://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML"></script>下面这段代码：
$$
e^x = \sum\_{n=0}^\infty \frac{x^n}{n!} = \lim\_{n\rightarrow\infty} (1+x/n)^n
$$显示的效果： 显示行内公式的代码如下：
$$\alpha + \beta$$但是kramdown的解析引擎和转帖gist代码的插件、直接高亮文件中代码的插件include-code有冲突。
利用mathjax插件定义的新标签，也可插入公式。这段代码{% math %} e^x = \sum\_{n=0}^\infty \frac{x^n}{n!} = \lim\_{n\rightarrow\infty} (1+x/n)^n {% endmath %}也可显示和上面一样的公式，利用标签{% m %} \alpha + \beta {% em %}可显示行内公式。mathjax还支持公式编号，引用公式\eqref{eq:sample}很方便。
\begin{equation} \int_0^\infty \frac{x^3}{e^x-1}\,dx = \frac{\pi^4}{15} \label{eq:sample} \end{equation}
另外一些支持公式的方案可参考：Kramdown的Math Blocks、Maruku的公式支持。 其他和学术写作相关的插件有：jekyll-scholar、jekyll-citation、bibjekyll。
###其它
显示相关文件的插件用related_posts-jekyll_plugin、只显示第一段的插件，可解析类似wordpress的<!--more-->标记的excerpt插件，美化引用格式的blockquote插件。octopress的插件可以直接用于jekyll中。
###小结
要将jekyll的页面托管在github时，推荐尽量不用github之外的插件。代码高亮用pygments，markdown的解析器用kramdown更利于对公式的解析，如果还要其它一些美化，就直接插html代码吧！
常用的Jekyll变量
##一些技巧
###直接插入gist代码
因为markdown的语法可以兼容html，在情非得已的情况下，直接查html代码。如果转帖gist的代码，直接在markdown文件中插入：
<script src="https://gist.github.com/834610.js?file=Jekyll nd Octopress Liquid tag for MathJax.rb"></script>即可得：
###页内跳转
为了方便页内快速跳转，可建立空内容的锚点。比如
<span id="jekyll-and-github"></span>
##jekyll与github的关系既可用
[回去看看](#jekyll-and-github)实现页内跳转，试试，回去看看。如果用的是kramdown解释器，上例中空锚点行下须有一空行。
###表格不断行
表格某一栏不断行的处理：
<span style="white-space:nowrap">git clone username@host:/path/to/repository</span>###引用本站其它网页
{% post_url your_markdown_file_name %}