Upgrading to Jekyll 3.0

Jekyll 3.0 was released recently. I decided to upgrade from version 2.5.2.

I kicked the upgrade off by running sudo gem install jekyll.¹ This post documents both the site improvements I made and the gotchas I encountered.

A few quick fixes

At first, Jekyll 3 would not build my site. I was able to get things working after making a few changes.

1. Jekyll 3 no longer supports relative permalinks, so I removed the following line from my _config.yml:

    relative_permalinks: true
   

2. As the following warning indicates, Jekyll 3 no longer lets you use pagination without explicitly adding the jekyll-paginate gem:

    Deprecation: You appear to have pagination turned on, but you haven't included the `jekyll-paginate` gem. Ensure you have `gems: [jekyll-paginate]` in your configuration file.
   

   I added the line to my config file, then used sudo gem install jekyll-paginate to get a local copy.

3. Another gem that must now be explicitly listed is jekyll-gist.² After installing it locally with gem install jekyll-gist, I added it to my _config.yml:

    gems: [jekyll-paginate, jekyll-gist]
   

4. Another error comes from the fact that Redcarpet is no longer included by default. This resulted in another error:

    Dependency Error: Yikes! It looks like you don't have redcarpet or one of its dependencies installed. In order to use Jekyll as currently configured, you'll need to install this gem. The full error message from Ruby is: 'cannot load such file -- redcarpet' If you run into trouble, you can find helpful resources at http://jekyllrb.com/help/!
   

   Rather than adding the Redcarpet gem, I decided to switch to Kramdown.

Redcarpet to Kramdown

I discovered recently that Redcarpet interferes with MathJax. A lot. When entering inline math, I often found myself needing to escape underscores like this: $ \dot{x}\_1 $. The Jupyter notebook markdown processor does not require this modification, so I could never count on notebook markdown to work on my website. Annoying.

Display blocks are even worse. In order to render math like the following, I needed to just wrap the whole thing in a <p> HTML tag:

\begin{align}
\label{eq:2a}z_1^\top C z_1 &= \lambda_1 s^2 + z_1^\top b \\
\label{eq:2b}z_2^\top C z_2 &= \lambda_2 s^2 + z_2^\top b \\
\label{eq:2c}z_1^\top C z_2 &= \lambda_2z_1^\top z_2 + b^\top z_1 \\
\label{eq:2d}z_2^\top C z_1 &= \lambda_1z_2^\top z_1 + b^\top z_2 \end{align}

Again, too much work for math-heavy posts. From what I’ve read, Kramdown is more sensitive to $ and $$ delimiters, so I decided to give it a try. Because Jekyll 3 uses Kramdown by default, I can switch by removing the following line from my config file:

markdown: redcarpet

I would like to use GitHub-Flavored Markdown, which supports fenced code blocks (where you use three tildes to escape blocks of code):

kramdown:
  input: GFM

In addition to respecting my $\LaTeX$, Kramdown provides tables of contents and even provides footnotes.³ It also implements deep-linking automatically, without any jQuery hackery. Switching seems to be the right move.

Pygments to Rouge

Jekyll 3 also uses Rouge instead of Pygments. I figure I might as well switch there too. If it’s good enough for GFM, it’s good enough for me. I removed this line from my config file:

highlighter: pygments

Then I added a line to my Kramdown configuration:

kramdown:
  input: GFM
  syntax_highlighter: rouge

Julia test:

function f(x)
    return x^2
end

Python test:

def test():
    print("hello world")

Unfortunately there is no Julia highlighting support yet. It looks like the issue will be fixed soon. In the meantime, I can take comfort in the fact that I typically embed large blocks of Julia code using the gist liquid tag. I can cope with a temporary lack of Julia highlighting support.

Wrap-up

I gained a lot in the Jekyll 3 upgrade. I did need to make a couple miscellaneous changes. Be on the lookout for these if you are upgrading your own site:

• Anytime I want to render a dollar sign, I need to escape it twice using \\$. If I escape it once, MathJax still considers it an inline math environment. Perhaps there is a way to configure MathJax or Kramdown to avoid this, but I don’t type dollar signs very often so it doesn’t merit further attention.
• When I use the <img> tag, I need to ensure that the path following src= is enclosed in double quotes. Otherwise Kramdown renders the tag as plaintext.

Update

After pushing my upgraded site to GitHub Pages, I realized Pages doesn’t support Rouge. It looks like GitHub will eventually release their own highlighter called PrettyLights, but in the meantime Pygments is the preferred option. Unfortunately Pygments doesn’t work with Kramdown without some hackery (which probably isn’t supported by Pages). It looks like Jekyll development has steered sharply away from the GitHub Pages configuration. Hopefully Pages adds support for a Kramdown-compatible syntax highlighter soon, because I’ve decided I love Kramdown.

Footnotes