just wasting bandwidth...

Portable Jekyll

Upgrading to Jekyll 2.3.0 on Windows

Published on 01 September 2014


During the last summer holidays, I finally managed to prepare my new laptop, installing and configuring all the (many) applications I use at work. The last software I needed to install before I could get rid of the old laptop was Jekyll with Pygments. Jekyll is the software I use to generate this site, as described here and also here.

I had first installed Jekyll on my old Windows laptop back in 2010, and I remembered that setting up the whole thing on Windows was not exactly straightforward… so I was a little worried about having to repeat the whole task, which had required a considerable amount of time. But at that time Jekyll was in a quite initial stage of development (the version on my old laptop was 0.11.0, while the current version is 2.3.0), so I was hoping that in the years maybe the installation process had become more straightforward.

In fact, here I found a detailed procedure which describes how to set up Jekyll on Windows (sadly, this guide was not available back in 2010). As you can read, it involves installing Ruby, the Ruby DevKit, the Jekyll gem, Python, pip, Pygments and editing a few files to configure the whole stuff. Not straightforward as I was hoping. But on that same page is also noted that a portable version of Jekyll, Portable Jekyll, now exists. So I decided to give it a try.

I downloaded the last version of Portable Jekyll from github. The 800+ Mb zip (!) contains Jekyll 2.3.0 and everything that is required to run it on Windows, including Pygments. Then I decompressed the zip file and adjusted the scripts I used to generate my site with the previous 0.11.0 version. In more detail I had to add this line to the beginning of my batch scripts:

call "C:\PortableJekyll-2.3\setpath.cmd"

The setpath.cmd file is shipped with Portable Jekyll and is invoked to update the PATH environment variable with the paths that are required by Jekyll and Pygments.

Then, in the same scrpts, I had to fix the jekyll command syntax, which changed since version 0.11.0:

  • jekyll changed to jekyll build: this is the command that builds the site
  • jekyll --server --auto changed to jekyll serve --watch: this is the command that starts the embedded webserver with automatic site regeneration enabled

The first run of the new version of Jekyll resulted in an error due to a wrong entry in my old _config.yml configuration file: the pygmentize: true parameter I was using with the old version of Jekyll has been deprecated in Jekyll 2.3.0. Replacing the deprecated entry with highliter: pygments resolved the issue.

Once I fixed the configuration file, Jekyll started complaining about some special characters that were present in a couple of my Maruku files. After removing those characters, the site was generated almost correctly. The last problem was due to the character encoding: the previous version of Jekyll generated the HTML pages with ISO-8859-1 encoding, while version 2.3 by default generates HTML pages with UTF-8 encoding. As a results, some special characters where not being correctly rendered in the browser. To fix this last issue I simply changed the encoding declared in the header of my HTML pages from:

<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />


<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />

Good enough. This site is now generated with Jekyll 2.3.0.

Fabrizio Fantini 01 September 2014

blog comments powered by Disqus