Syntax highlighting in a Jekyll blog

12 February 2017

The official documentation for Jekyll says that it:

has built-in support for syntax highlighting of code snippets using either Pygments or Rouge, and including a code snippet in any post is easy. Just use the dedicated Liquid tag as follows:

Jekyll's expected output

Now, if you’re new to Jekyll and you follow these instructions, it might not work. Here’s why:

Jekyll recognises that there’s code there but doesn’t know what colours to use. You need a stylesheet detailing the css for that, and save it to your css directory as syntax.css

Because you’re referring to a new stylesheet, you need to call this in your _layouts/default.html head, as follows:

<link href="/blog/css/syntax.css" rel="stylesheet">

This needs to include “site.baseurl” in double curly braces at the start of the address. I have included it but for some reason it’s being stripped out.

Make sure your _config.yml is correct:

markdown: kramdown
highlighter: rouge
kramdown:
  input: GFM
  hard_wrap: false
  syntax_highlighter: rouge
  extensions: fenced_code_blocks

And finally, when you use fenced code blocks, use 4-spaces before each line of code. Jekyll’s local build was recognising this as code without the 4-spaces but the commit to Github seemed to strip it out.

Thanks to @demisx for his post and talk.jekyllrb.com user @rdyar on this issue.