Geert Vanderkelen: Jekyll 3.0 beta7, looking good

Putting on my adventure boots, I have installed Jekyll 3.0 beta7. Since Ruby and the whole gem realm is completely new to me, I expect things wrong to go sougth. But it wasn’t that bad.
This blog post is probably meant for those trying out the Jekyll 3.0 beta, but also for those upgrading.

Liquid syntax

First, a few error messages and maybe it is something that will hit a few folks out there. Jekyll 3.0 is using Liquid 3.0 and it seems to be not so forgiving when it comes to unescaped syntax. Since I have quite a few examples in Python, I have code which potentially does weird things with str.format().

  Liquid Exception: Liquid syntax error: Expected end_of_string but found colon in "{{nr:3}}" in ...

This is simply matter of putting the code in a raw-block:

 {% raw %}
 ```python
 print("{{nr:{0}}}".format(2))
 ```
 {% raw % }             # Extra space is to fool Liquid

Default now kramdown

The default Markdown converter is now kramdown (was maruku). I had already configured kramdown, but this what you probably want in your _config.yml in the future:

markdown:kramdown

If you like the GitHub Markdown variation, for example, fenced code blocks, you still can set options for kramdown like this:

kramdown:input:GFMsyntax_highlighter:rouge

I only use GFM because of the backticks. Using anything else makes little sense to me.

Syntax Highlighter

Jekyll seems to slowly move away from Pygments towards Rouge. The simple rational is to remove the Python dependency. As a Python guy, I encourage this. I wouldn’t like to be dependent on Ruby in my Python projects either.

One issue I had with Jekyll 3.0 beta is that suddenly, Rouge was not doing its magic. I had a hard time debugging it and finally found the issue while ‘fixing’ kramdown. The problem was that kramdown could not load the rouge file.

Once I knew the issue with the require in kramdown, the problem was rather quickly found: Rouge is not in the ``$LOAD_PATH`. But why? It’s an issue with Bundler and Jekyll, and Jekyll guys are a bit fighting with it apparently.

The following works (if you use Bundler of course):

$ bundle exec jekyll build

It’s ungly to use bundle exec, so I did a final bundle update, and that seemed to have done the trick. Now Jekyll had the correct $LOAD_PATH and it is generating syntax highlighted code again.

I still don’t really understand all the magic there though. Ah yeas, make sure to uninstall previous version of Jekyll and adapt your Gemfile. At a minimum, the following:

gem 'jekyll', '>= 3.0.0.beta'
gem 'rouge', '= 1.9.0'
gem 'liquid', '~> 3.0'

Incremental Regeneration

I have a relative small blog, like 400 blog posts. Regeneration of the site takes like 7 seconds with Jekyll 3.0. It’s a bit fast than Jekyll 2.5. If you choose not the make the full site, it’s indeed much faster.

If you add a blog post, the post will be generated quickly and available right away to view offline. It will, however, not be available in your post overview. Maybe this is something that still needs to be worked out, but it might confuse you. Just don’t push the reload button like mad (like I did).

Further hacking

I will use the new documents feature in Jekyll 3.0 as well as hooks. I currently have a plugin for creating redirects, but it is going to be perfect for making my first hook. Since I have the beta now generating my site just like it does with Jekyll 2.5, I will start playing soon.