Jekyll, Github Flavored Markdown and footnotes

Update: As of Jekyll 2.0.0 it’s possible to have our GitHub Pages cake and eat it :)
See this new post for more details.

Jekyll uses redcarpet as its default Markdown parser for newly generated sites as of version v1.1.0. It does so by setting markdown: redcarpet in _config.yml.
Redcarpet is the markdown parser used by GitHub, but in its default config it actually doesn’t parse using the GitHub Flavored Markdown (GFM) rules.

To change this add the following to Jekyll’s _config.yml:

redcarpet:
  extensions:
    - hard_wrap
    - no_intra_emphasis
    - autolink
    - strikethrough
    - fenced_code_blocks

This is also documented on the Jekyll documentation on GitHub about GitHub pages in the chapter Mimicking Github Flavored Markdown. Unfortunately this isn’t available in the publicly available documentation on the Jekyll website.

Footnotes #

Unfortunately only the current master branch of redcarpet supports footnotes (and Jekyll doesn’t even support v3.0.0 at the moment) so with the default setup it isn’t possible to add footnotes to posts.

Luckily there are other MarkDown parsers to choose from. A short comparison of them can be found on bloerg.net.

Just like Matthias concluded in this comparison I came to the conclusion that at the moment kramdown is the best option to use as my MarkDown parser. Unlike Matthias I feel no need to use Code Highlighting using Pygments because CodeRay (don’t mind the ugly site!) works perfectly fine for me, I don’t have to modify Jekyll or Kramdown or have to use workarounds to make Jekyll parse the MarkDown files correctly and it just feel (c)leaner to me to stay with only Ruby dependencies.

Using Kramdown inside Jekyll #

Using Kramdown inside Jekyll is very easy, the only thing you have to do is set the markdown configuration option in your _config.yml to kramdown (and install the kramdown if it isn’t installed already).

markdown: kramdown

Since I still want to make use of GFM some additional settings from kramdown have to be set just like with redcarpet. Kramdown actually already supports most of the parsing features needed for GFM, but uses tilde’s for fenced code blocks and doesn’t add hard line-breaks inside paragraphs. This is easily fixed though by setting the kramdown input configuration option to GFM in your _config.yml.

markdown: kramdown

kramdown:
    input: GFM

That’s it, now you can use GFM and footnotes¹ in your Jekyll MarkDown posts!

Example footnote. ↩