Installing Jekyll on Windows is a royal pain. GitHub claim in the article "Using Jekyll with Pages" that installing Jekyll is easy. However, I beg to differ, and in this blog I describe in detail the steps I took to get Jekyll up and running on Windows. I am a big fan of open source software and the volunteers who make possible great products like Jekyll. I generally shrug off these kind of installation issues and move on. However in the case of Jekyll I give a blow by blow account of this installation.

Part of the problem is that it is surprising difficult to install the Ruby language in the first place on Windows. This is my first install of a Ruby application as well as my first intall of the Ruby language environment itself. So this blog is like a case study of a fresh Ruby application install on a clean Windows PC.

Overview of Jekyll Installation Steps

The reference article for this install is "Using Jekyll with Pages" from GitHub - I found these installation steps insufficient and incomplete. The actual steps I followed to install Jekyll on my Windows 7 PC are as follows:

1. Install Ruby on Windows
2. Download Ruby Development-Kit on Windows
3. Install Ruby Development-Kit on Windows
4. Install Gem Bundler
5. Setup the file named Gemfile
6. Install Jekyll
7. Fix the windows hittimes bug
8. Run the Jekyll server

Installing Ruby on a Windows PC

The first step in installing Jekyll is to install the Ruby programming language. This is needed because Jekyll is coded in Ruby. Here is how I installed Ruby on my Windows desktop.

1. Navigate to the Ruby page for Windows: RubyInstaller for Windows
2. There is a choice of three versions of Ruby to download - I choose the latest version. This is Ruby 2.2.2 - see link on top left hand side of page. Note that this is the 32-bit version of Ruby. The page advises to use 32-bit version on windows.
3. I had no issues installing Ruby 2.2.2 on my PC. From the installer options it is important to choose the option to "Add Ruby executables to your PATH".

I find the Ruby Windows download page cluttered and confusing. I expected a page with a big button labelled "Download Latest". Instead to my surprise I had to decide which of seven available Ruby versions I should choose.

Installing Ruby Development-Kit on a Windows PC

This mandatory step is missing from the "GitHub Jekyll setup page".

1. Navigate to the Ruby page for Windows: RubyInstaller for Windows
2. I choose the development kit from bottom left hand side of screen. I selected the development kit labelled "For use with Ruby 2.0 and 2.1 (32bits version only)".
3. The development kit is packaged as a 7-Zip archive.
   The next step is to extract the development kit into a Windows folder - I extracted the kit into a new folder downloads\rubydev

Installing Ruby Development-Kit on a Windows PC

This mandatory step is missing from the "GitHub Jekyll setup page".

1. You need to navigate to a new Ruby web page to for the instructions to install the Ruby development kit.
2. Here is how I installed the Ruby Development kit:
   • open a Windows Command line window
   • navigate to the installation folder specified above - in my case "cd downloads\rubydev".

3. run the following commands:

   ruby dk.rb init
   ruby dk.rb install

The above commands ran without error - this completed the install of Ruby and the development kit.

The Ruby Windows page contains the link for downloading the Development-Kit - but no instructions on on to install it. I had to use Google to find these install instructions.

Install Gem Bundler

Bundler is a package manager that makes versioning Ruby software like Jekyll a lot easier. To install Bundler, run the command:

gem install bundle

This command ran without any errors.

Setup the file called Gemfile

The file called Gemfile is required in the root directory of the web-site repository - in my case the patclaffey.github.io repository. The GitHub installation instruction page called "Using Jekyll with Pages" gives incorrect instructions for this file. The GitHub instructions are to create Gemfile with a single line as follows:
gem 'github-pages'

If Gemfile is created as above then the next step (Jekyll installation) fails with the following error:

The fix for this Jekyll installation error is to create Gemfile with the following two lines:

source 'https://rubygems.org'   
gem 'github-pages'   

Install Jekyll

To install Jekyll, run the command: bundle install This command should without any errors, provided that Gemfile is setup correctly.

Fix Hitimes Require Error (Windows Ruby 2.2 Issue)

The command to run the Jekyll Server (from repository root directory) is :

bundle exec jekyll server    

On Windows, when using Ruby 2.2, this results in the following Hitimes Require Error.

The fix for this error is described in StackOverflow article "Hitimes Require Error when running Jekyll serve on windows".

Running the Jekyll Server

The command to run the Jekyll Server (from repository root directory) is :

bundle exec jekyll server    

Here is output from this command on my PC:

I can view the output served by Jekyll in my desktop browser at the url http://localhost:4000

Conclusions

The GitHub instructions at "Using Jekyll with Pages" underestimate the difficulty of installing Jekyll. They say that a Jekyll installation is easy - this is certainly not my experience. For example they omit instructions about downloading and installing the Ruby Development-Kit. They should also give crystal clear instructions on the contents of Gemfile.

The Ruby Community should simplify and clarify the instructions for installing Ruby and the Ruby Development-Kit on Windows. For example a one-click express install for Windows would be very welcome.

The Ruby Windows Hittimes bug should be fixed - this is the only software related issue found in this install.

Jekyll works well on Windows - this blog was written on Windows and successfully pre-viewed on my PC using Jekyll.