Better GitHub-style syntax highlighting with Rouge

This is a sequel to my earlier post: GitHub-style syntax highlighting with Pygments - I recently updated the way I do syntax highlighting on this site, so here’s a quick writeup of how I’m doing it. As before, here’s a snippet of Ruby code to demonstrate how the highlighting looks:

class A < B; def self.create(object = User)
class Zebra; def inspect; "X#{2 + self.object_id}"

module ABC::DEF
  include Comparable

  # @param test
  # @return [String] nothing
  def foo(test)
    Thread.new do |blockvar|
      ABC::DEF.reverse(:a_symbol, :'a symbol', :<=>, 'test' + test)
    end.join
  end

  def [](index) self[index] end
  def ==(other) other == self end
end

anIdentifier = an_identifier
Constant = 1
render action: :new

Of course better is a very fuzzy term - but some advantages over the previous approach:

• Rouge is 100% Ruby-based. So no more having to rely on the (albeit excellent) python-based Pygments - which always felt like a bit of a hack
• Easier line numbers, without any extra CSS. Has the added advantage of universal browser support.
• middleman-syntax uses Rouge by default in version 1.2+

This post focuses on middleman (which this site is built on) but rouge can be used with Rails¹ or Sinatra² too.

Setup

To enable basic syntax highlighting, we need to add the middleman-syntax gem to our Gemfile:

gem "middleman-syntax"

and activate it in our config.rb:

activate :syntax

Finally we’ll enable line numbers with the aptly-named line_numbers option:

activate :syntax, line_numbers: true

Styling

Most of the work is done already, thanks to richleland’s Github color scheme. We just need to tweak the first line, to replace .hll with .highlight

.hll {
  background-color: #ffffcc;
} /* WRONG */
.highlight {
  background-color: #ffffcc;
} /* RIGHT */

And we’ll add a little extra CSS to style our <pre>, add some extra padding, and prettify the line numbers a bit.

pre {
  border: solid 1px #ddd;
  background: #fff;
  padding: 0;
  line-height: 23px;
  margin-bottom: 30px;
  white-space: pre;
  overflow-x: auto;
  word-break: inherit;
  word-wrap: inherit;
}

.highlight td {
  padding: 8px 15px;
}

.gl {
  background: #fafafa;
  border-right: 1px solid #ddd;
  color: #999;

  /* Stop line numbers being visually selected */
  -webkit-touch-callout: none;
  -webkit-user-select: none;
  -khtml-user-select: none;
  -moz-user-select: none;
  -ms-user-select: none;
  user-select: none;
}

Markdown

I couldn’t get rouge to play nicely with Redcarpet on middleman - so I decided to switch to Kramdown, which I highly recommend. It’s written in pure Ruby, and comes with fenced code blocks out-of-the-box, as well as footnotes and a bunch of other useful features³.