Installing Jekyll on Windows 8 (64-bit)

This is my working formula for getting the Jekyll ruby gem up and running on Windows 8 (64-bit).

Every installation is different, and I make no claim that this will work for you exactly as-is, but hopefully I can save you having to go against some of the tricky bits.

Sure, you can manage a Jekyll site without installing the gem on your local computer. But doing so will allow you to preview your content before pushing it live to GitHub Pages. For help on getting set up with GitHub, start here.

What is Jekyll?

"Jekyll is a simple, blog-aware, static site generator. It takes a template directory containing raw text files in various formats, runs it through Markdown (or Textile) and Liquid converters, and spits out a complete, ready-to-publish static website suitable for serving with your favorite web server."

Learn more by going to the Jekyll website.

Notes

A couple of notes before we begin:

  • I tried Ruby 2.0 (64-bit and 32-bit) with no success. I'll probably give it another try in a few months, but for now I wouldn't recommend going through the trouble.

  • Python is required if you want to use Pygments. At the time of this writing it was necessary to downgrade to Python 2.7.5 and Pygments 0.5.0 in order to get rid of errors when running 'jekyll serve'. Instructions on downgrading Pygments at the bottom of these instructions. 

Steps

  1. Download:

    Python 2.7.5 Windows Installer
    Installs a Python interpreter on Windows. Necessary if you want to use Pygments (see note above).

    Ruby 1.9.3
    A Ruby installer. Ruby is the programming language behind Jekyll.

    Development Kit tdm-32-4.5.2
    Allows us to install Ruby gems written in C/C++ on Windows.

  2. Run python-3.3.2.amd64.msi (Directory: c:\Python33)

  3. Run rubyinstaller-1.9.3-p448.exe (Directory: c:\ruby)

    (checked) Install Td/Tk support
    (checked) Add Ruby executables to your PATH
    (checked) Associate .rb and .rbw files with this Ruby installation

  4. Run DevKit-tdm-32-4.5.2-20111229-1559-sfx.exe (Extract to: C:\DevKit)

  5. Open Command Prompt and enter the following:

    cd C:\DevKit

    Bind DevKit to Ruby installer:

    ruby dk.rb init

    then

    ruby dk.rb install

  6. Now we can install Jekyll. Enter the commands below in sequential order. The text in italics are expected messages.

    gem install jekyll

    Fetching: liquid-2.5.1.gem (100%)
    Fetching: fast-stemmer-1.0.2.gem (100%)
    ... some other stuff ...

    cd ..

    mkdir jekyll

    cd jekyll

    jekyll new mysite

    New jekyll site installed in c:/jekyll/mysite.

    cd mysite

    jekyll serve

    Configuration file: c:/jekyll/mysite/_config.yml
    Source: c:/jekyll/mysite
    Destination: c:/jekyll/mysite/_site
    Generating... done.
    ... some other stuff ...

  7. To view your site, in your browser go to 127.0.0.1:4000.

Troubleshooting

If you get something like this after typing 'jekyll serve'...

Generating... C:/ruby/lib/ruby/gems/1.9.1/gems/posix-spawn-0.3.6/lib/posix/spawn.rb:162: warning: cannot close fd before spawn [31m Liquid Exception: No such file or directory - /bin/sh in 2013-08-16-welcome-to-jekyll.markdown[0m done.

... then you may need to roll back Pygments to 0.5.0. (Thanks to zzheng at Stack Overflow.)

  1. Get your pygments version number:

    gem query --local

  2. Uninstall the current version (0.5.2):

    gem uninstall pygments.rb --version "=0.5.2"

  3. Install 0.5.0.:

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