Jekyll的渲染器

Jekyll中默认的markdown渲染器是maruku，但是它对Latex公式和中文支持都不太好, 通常是根据不同的需要选择其它几种渲染器（rdiscount，kramdown，redcarpet等），它们各有利弊。Github在后台则选用了Redcarpet作为其文本渲染器，因为它安全性高且性能卓越，同时它在基本Markdown语法的基础上增加了一些自己的特性。Kramdown是这几个当中对基础 Markdown语法拓展最多，也是最方便使用的¹（但是跟Pandoc相比，还是差得很远）。笔者之前一直是使用rdiscount，结果在本地编译没问题的代码在Github上就是无法通过，折腾了半天知道Github上的rdiscount是1.6.8版本，而本地rdiscount是2.1.6版本。下降版本后发现rdiscount1.6.8版本不支持注脚语法。使用低版本就无法使用注脚，使用高版本就无法在Github上编译通过，纠结之余开始寻找合适的解决方案，于是就有了这篇文章。

为什么使用pandoc

Pandoc被称为格式转换的瑞士军刀，功能强大，能够在数十种文件格式（如Markdown，reStructuredText，Textilte，HTML，LaTeX，pdf，doc等）中自如的转换，几乎能做到无缝兼容，且成熟稳定。使用Pandoc在Markdown文件中直接使用Latex公式，然后通过MathJax、jsMath 等等方式显示公式。例如使用下面一段Latex代码

$$e^{i\pi}+1=0$$

就可以得到一个优美的公式： $e^{i\pi}+1=0$ 为了能让公式在网页中显示，请在markdown文件头加上以下调用MathJax的代码。

<script type="text/javascript" src="http://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML">
</script>

因此选用Pandoc作为Jekyll中markdown的渲染器是很自然的。 但是Github Pages并没有提供pandoc的支持，也就是说使用Pandoc的网站代码在Github上是无法编译的，以后会谈到如何解决这个问题。下面先看看如何配置环境将Pandoc作为Markdown的渲染器。

配置Pandoc环境

1. 首先当然是安装Pandoc： Windows下直接从pandoc官网下载最新安装包安装即可。

2. 安装Pandoc-Ruby。这里假设已经转好Ruby、Jekyll等环境了，如果还没有安装请参考<>。
   直接使用以下命令即可安装Pandoc-Ruby

gem install pandoc-ruby

1. 安装Jekyll插件。直接从Github站点 Jekyll Plugin for Using Pandoc-Ruby下载pandoc_markdown.rb放到网站根目录下的_plugins文件夹中（如果_plugins文件夹不存在，就创建一个），Jekyll在每次编译生成网站前都会自动加载_plugins文件夹中的所有*.rb文件。Jekyll官网²上有该插件的相关介绍，同时也给出了其它的解决方案。

2. 在网站配置文件_config.yml中添加设置Markdown的渲染器为Pandoc。添加以下配置即可

markdown: pandoc
pandoc:
  format: html5
  extensions: [smart, mathjax]

一些修改

理论上经过以上的配置就可以使用pandoc渲染Markdown了，可是事情似乎并没有这么简单，执行jekyll server命令后，出现了下面的错误

Conversion error: There was an error converting .....
: undefined method 'convert' for [:smart, :mathjax]:Array. Use --trace to view backtrace

下载文件替换lib/jekyll/converters/markdown.rb即可，修改之处是在setup和convert中按照其它渲染器的格式增加一个pandoc判断。
至此，我们已经可以在本地Jekyll中使用Pandoc作为Markdown的渲染器了，至于Github Page不能编译通过的问题下次再讨论。

『上善若水，水善利万物而不争』