Github pages, Kramdown, Rouge, Jekyll 3.0: the final struggle

What this is about…

Github has recently announced Github pages was moving to Jekyll 3.0. Beyond better performances, this change also implies renuncing to Redcarpet and Pygments. From now, only Kramdown will be supported as the markdown engine. And Rouge will be the only syntax highlighter to work.

I have started to do the migration.
Unlike what Github indicated, this is far from being that easy. The most difficult part is about updating your local Jekyll installation to verify it works as expected. To be clear, there are still bugs in the last github-pages gem (in its dependencies). However, this article may help you to be as close as possible waiting for the fixes.

Reset your Ruby installation

First, Jekyll 3.0 requires Ruby 2.0 or higher.
If you are on Ubuntu, you will find Debian packages and instructions on this page.

Then, you may suffer from bad interactions with your previous Jekyll install. If you want to start from a brand new point, uninstall all your gems. This can be done in a single command line.

sudo gem list | cut -d” ” -f1 | sudo xargs gem uninstall -aIx

So far, so good.
Now, the best thing to do is to follow Github instructions and let the github-pages gem download the required dependencies. Verify your have a Gemfile file in your site sources with the following content.

source ‘https://rubygems.org’
gem ‘github-pages’

You may have other gems as well.
Make sure you DO NOT HAVE a Gemfile.lock file in the same directory. If so, delete it. Otherwise, you will keep on downloading the same old gem versions.

Eventually, run sudo bundle install.
This will download github-pages with all the right gems.

Once this is done, update your _config.yml file. Mine used to start with…

encoding: utf-8
markdown: redcarpet
highlighter: pygments
redcarpet:
  extensions: ["tables", "no_intra_emphasis"]

gems: [ "jemoji" ]

Now, it looks like…

encoding: utf-8
markdown: kramdown
highlighter: rouge
kramdown:
  input: GFM
  hard_wrap: false
  syntax_highlighter: rouge

gems: [ "jemoji" ]

And that should do the trick.
OK, on February 12th, it does not compeletly. First, there is a bug with Jekyll 3.1.1. This is why it is better to use github-pages and not installing directly the Jekyll gem. And then, there is also a bug with with the current github-pages. When using fency code blocks…

```properties
# Here in version %v_SNAP%
key = value
```

… the generated HTML is different from what pygments used to generate. Instead of generating…

<div class="highlight"><pre><code class="language-properties" data-lang="properties"><span class="c"># Here in version 0.5
</span><span class="py">key</span><span class="p"> = </span><span class="s">value</span>
</code></pre></div>
</blockquote>

… it generates…

<div class="highlighter-rouge"><pre><code><span class="c"># Here in version 0.5
</span><span class="py">key</span><span class="p"> = </span><span class="s">value</span>
</code></pre></div>
</blockquote>

The language-properties CSS class disappears.
According to this topic, this is fixed in Jekyll 3.1.2. So, let’s wait for it!

Edit from March 4th: in fact, it is a current limitation of Rouge. See jneen/rouge#379 for more details.


About this entry