GitHub Pages, now with GitHub Flavored Markdown, footnotes and syntax highlighting

Update: As of the first of February 2016 GitHub Pages handles GFM, footnotes and syntax highlighting out of the box, no configuration required.
See this new post for more details.

In contrast to what I wrote 1,5 years ago it’s now possible to use all of GitHub Flavored Markdown’s features combined with footnotes and syntax highlighting on your Jekyll site whilst still having GitHub Pages build your site for you.
Building your site locally and then pushing the resulting HTML is a thing of the past! :)

Intro #

As of Redcarpet version 3.1.0 Markdown footnotes support was added. Since both Jekyll 2.0.0 updated its Redcarpet dependency to this version and GitHub Pages’s version of Jekyll has been updated to version 2.2.0 as of 30.06.2014 as well this finally allows us to enable all GitHub Flavored Markdown features using Redcarpet’s extension as well as having syntax highlighting when using GitHub Pages to build our website! :)

Setup #

The basic setup consist of the Redcarpet Markdown parser with several extensions enabled combined with Pygments for syntax highlighting.

GitHub Flavored Markdown with Redcarpet #

We start with the same settings as in the old Redcarpet setup and simply add footnotes to the list of extensions we want to enable in _config.yml.

Also, fenced_code_blocks can be removed as this is already being set by Jekyll.

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

Et voilà, footnotes¹!

Note: If you want to enable some nice “smart” typographic punctuation enhancements you can add the smart extension, which enables SmartyPants.

Syntax highlighting with Pygments #

The old Kramdown setup didn’t support syntax highlighting on GitHub Pages because Kramdown doesn’t support Pygments, the only syntax highlighter currently available on GitHub Pages. It only supports the Coderay and Rouge syntax highlighters and these are unavailable when building on GitHub Pages.

To use Pygments we only have to set the highlighter option in _config.yml to pygments:

highlighter: pygments

Jekyll actually already defaults to Pygments at the moment of writing this post so doing this isn’t really necessary :)

Combined with Redcarpet’s fenced code blocks extension this gives us syntax highlighting that works for both the highlight liquid tag as well as within fenced code blocks.

This is a footnote! ↩