Andrzej Jóźwiak
"For every complex problem there is an answer that is clear, simple and wrong!"

June 28, 2014

Jekyll on Windows

According to Jekyll project site, installing and using their tool is easy like 1, 2, 3 but unfortunately I’ve quickly found out that there’s more to it on Windows. You will have to get certain versions of Ruby, Python and Ruby Development Kit and then keep your fingers crossed as there is a lot that can go wrong.

Its Windows, so the rule of a thumb is:

  1. don’t use white chars in directory names
  2. C:\ drive is your friend, putting something there = less problems later
  3. remember to add executables to system variables like PATH

I’ve installed Ruby version 1.9.3 to C:\Ruby193 and added it to PATH and went with installing the jekyll gem. I got:

C:\Users\Andr3y>ruby --version
ruby 1.9.3p545 (2014-02-24) [i386-mingw32]

C:\Users\Andr3y\gem install jekyll
Fetching: liquid-2.5.0.gem (100%)
Fetching: fast-stemmer-1.0.2.gem (100%)
ERROR:  Error installing jekyll:
        The 'fast-stemmer' native gem requires installed build tools.

Please update your PATH to include build tools or download the DevKit
from 'http://rubyinstaller.org/downloads' and follow the instructions
at 'http://github.com/oneclick/rubyinstaller/wiki/Development-Kit'

To be really honest I was not surprised it didn’t work right from the start. I’ve installed it to C:\Ruby193DevKit after that you need to run two commands: ruby dk.rb init and ruby dk.rb install.

C:\Ruby193DevKit>ruby dk.rb init
[INFO] found RubyInstaller v1.9.3 at C:/Ruby193

Initialization complete! Please review and modify the auto-generated
'config.yml' file to ensure it contains the root directories to all
of the installed Rubies you want enhanced by the DevKit.

You can check if init was successfull with a ruby dk.rb review:

C:\Ruby193DevKit>ruby dk.rb review
Based upon the settings in the 'config.yml' file generated
from running 'ruby dk.rb init' and any of your customizations,
DevKit functionality will be injected into the following Rubies
when you run 'ruby dk.rb install'.

C:/Ruby193

I’ve read that you could get Invalid configuration. Please fix 'config.yml.' after using ruby dk.rb review when installing Development Kit on Windows. If this happens for you a change to config.yml is needed. This file is contained in main Development Kit installation directory. In case of my installation its C:\Ruby193DevKit\config.yml.

The file should look more or less like this:

# This configuration file contains the absolute path locations of all
# installed Rubies to be enhanced to work with the DevKit. This config
# file is generated by the 'ruby dk.rb init' step and may be modified
# before running the 'ruby dk.rb install' step. To include any installed
# Rubies that were not automagically discovered, simply add a line below
# the triple hyphens with the absolute path to the Ruby root directory.
#
# Example:
#
# ---
# - C:/ruby19trunk
# - C:/ruby192dev
#
---
- C:/Ruby193

Then simply use ruby dk.rb install:

C:\Ruby193DevKit>ruby dk.rb install
[INFO] Updating convenience notice gem override for 'C:/Ruby193'
[INFO] Installing 'C:/Ruby193/lib/ruby/site_ruby/devkit.rb'

Installing them gem is simple as gem install jekyll, everything was fine and dandy I could create a new static website with: jekyll new blog-test. Problems started when I tried to build it:

E:\Projekty\blog-test>jekyll server
Configuration file: E:/Projekty/blog-test/_config.yml
            Source: E:/Projekty/blog-test
       Destination: E:/Projekty/blog-test/_site
      Generating...
C:/Ruby193/lib/ruby/gems/1.9.1/gems/posix-spawn-0.3.8/lib/posix/spawn.rb:162: warning: cannot close fd before spawn
'which' is not recognized as an internal or external command
‹[31m  Liquid Exception: Failed to get header. in _posts/2014-06-19-welcome-to-jekyll.markdown‹[0m
jekyll 2.0.3 | Error:  Failed to get header.

What a Unix command which is doing on my Windows machine? I started looking for the answer and the most common answer for such question was to reinstall pygments. Most people around the web advised using pygments version 0.5.x. You can check what version of pygments you have with: gem list. Reinstalling is simple:

gem uninstall pygments.rb
gem install pygments.rb --version "=0.5.0"

In the command above I’m installing version 0.5.0 but any 0.5.x should be good.

Unfortunately after that change jekyll server command still was finishing with an error. After digging a bit I found out its the Python version causing the problems. I had Python from 3.x line and for jekyll you need 2.7.x line. So one download, reinstall, path change later I was ready to go and generated my test blog.

E:\Projekty\blog-test>jekyll server
Configuration file: E:/Projekty/blog-test/_config.yml
            Source: E:/Projekty/blog-test
       Destination: E:/Projekty/blog-test/_site
      Generating...
                    done.
Configuration file: E:/Projekty/blog-test/_config.yml
    Server address: http://0.0.0.0:4000/
  Server running... press ctrl-c to stop.

I hope this helps you!