Slapping on the rouge

The markdown processor and syntax highlighter used by an instance of Jekyll are configurable, yielding different results (or forcing certain development practices). Trawling through a few blog posts on the topic a while back suggested I use a combination of Kramdown for parsing Markdown and Redcarpet syntax highlighting. Within the last few days, pushing my blog to Github has resulted in a warning that Github Pages would only support Kramdown (phew) and Rouge (oh) in the future. I was unhappy with the highlighting (the colours felt watery and I didn’t really grasp the process firmly) and would soon have to change highlighter anyway, I decided to solve both issues.

With one hand

A post by Sacha Schmidt shows the basic Rouge/Jekyll configuration. First install Rouge (and kramdown if you’re not already):

gem install kramdown rouge

Then update your “_config.yml” to configure jekyll to use the right combination of tools and settings:

markdown: kramdown

kramdown:
  input: GFM
  syntax_highlighter: rouge

The input: GFM line tells kramdown to output “Github Flavoured Markdown”. GFM Allows for the “fenced code blocks” with programming language labels shown above, and other features.

With no hands

In my case, I didn’t need to run the gem install command. I had recently re-started development of the blog following a suggestion from several tutorials to use Github’s own github-pages gem. This gem helps keep versions of all the tools up-to-date and in sync with the ones Github are using. As a result, I already had Kramdown and Rouge installed and only needed to change my configuration.

Choosing a better palette

Rouge can use colour schemes designed for the Pygments syntax highter. Sacha had kindly linked a collection of CSS renderings of popular Pygments themes in their post. I copied one I liked into my Jekyll project…

$ cp ~/Downloads/pygments-css ~/Documents/make/my-blog-site/_sass/_zenburn.scss

… and updated the “main.scss” to import it:

@import
        "base",
        "layout",
        "zenburn"
;

This didn’t generate the colour scheme I wanted. Rouge outputs HTML elements for the code blocks beneath the highlighter-rouge classname, and applies the highlight classname to several of the children. The Pygments-derrived CSS file I was using expected to hook onto the .codehilite classname. I sought a way to change Rouge’s output, but didn’t unearth a solution - Rouge’s documentation claims to permit customisable classnames but I couldn’t pass the configuration parameter from Jekyll to Rouge. So I changed the CSS file to match the output:

.highlight code, .highlight pre, pre.highlight {color:#fdce93;background-color:#3f3f3f}
// ...

I also had to add the pre.highlight selector (shown above), to match the pre blocks in the HTML. I’m surprised I had to do this, given a general implication from Github and the Rouge developers that “it just works”.

Observations

I found it hard reaching a comfortable level of understanding about all this. It seems Jekyll and Github Pages have undergone several changes each over the last two or three years. Many blog posts and StackOverflow conversations describe the problem at points along development of these tools, but without painstakingly checking the dates on each post, it’s not obvious which combinations will work best. I imagine this post will become one such node in the Markov chain of blogging development history…

Sacha’s post suggests that Rouge would be a good choice, but then also contains an update (from early 2015) that Github Pages weren’t preparaed to support it. Later, I found this announcement from Github themselves describing the decision to only support it.

Many posts talk about a tool called Pygments, a syntax highlighting tool written in Python. For several years, developers considered it go-to tool for this job, even in non-python projects. Many of the Ruby syntax highlighters made use of Pygments under-the-hood. Rouge claims high compatability with everything Pygments, which makes transitions between the two easier and allows Rouge to use styles created for Pygments. However, the popularity of Pygments leads many people to defer to it: their own tools become under-documented because “it’s just like Pygments”. For those of us who’ve not used Pygments nor learned its wiles, this lack of documentation is frustrating.