Running Jekyll on Windows

Jekyll can also be made to run on Windows Operating System. This prefer when I am working on my office laptop which has Windows 7 installed on it.

Following packages are required to setup Jekyll on Windows:

• Ruby & Ruby Development Kit : Can be installed from here
• Jekyll
• Python : I strongly recommend using 2.7.5 as opposed to version 3. I used the portable version available here
• Pygments

1 Install the Ruby from http://rubyinstaller.org/downloads/ and install it to path such as C:\ruby

2 Download “DEVELOPMENT KIT” installer that matches the Windows architecture and the Ruby version just installed. For example, DevKit-mingw64-64-4.7.2-20130224-1432-sfx.exe is for 64-bit Windows with Ruby 2.0.0 x64. Install the Ruby development kit from the same location above and extract it to path such as c:\devkit.

Run the following commands

ruby dk.rb init

to generate the config.yml file to be used later in this Step

3 Edit the generated config.yml file to include installed Rubies. For example, in our case, it will look 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:/ruby

4 Run the following command to install to DevKit enhance your installed Rubies. This step installs (or updates) an operating_system.rb file into the relevant directory needed to implement a RubyGems

ruby dk.rb install

5 Install Jekyll using following command

gem install jekyll

6 Now, you can start using Jekyll. If you require code highlighting using pygments as well, follow the additional steps as well.

7 Now we need to install, easy_install. This can be installed from http://pypi.python.org/pypi/distribute Download distribute_setup.py and run the following command in python

python distribute_setup.py

8 Now to install pygments, simply run this command:

Note that using Pygments version 0.5.0 is highly recommended. Latest version of Pygmnents has issues with Jekyll.

easy_install Pygments 	

9 Start Jekyll

Following the commands on official Jekyll Quick-start guide, a new Jekyll blog should be able to be created and browsed at localhost:4000.

jekyll new myblog
cd myblog
jekyll serve

Now browse to http://localhost:4000

#Troubleshooting#

Liquid error: Bad file descriptor

You are likely to hit this error if you are using Python version >3 as opposed to 2.7.5 as mentioned in the beginning

Liquid error: Bad file descriptor

TypeError: Can't convert 'bytes' object to str implicitly

These are known issues and the resolution has been discussed here: https://github.com/rtomayko/posix-spawn/issues/17

This requires a change in C:\ruby\lib\ruby\gems\1.9.1\gems\albino-1.3.3\lib\albino.rb file.

I have created the gist of the changes required here

Build Failed

This will occur if Pygments is not installed. In that case, edit the _config.yml and Change ‘pygments: true’ to ‘pygments: false’

Pygments not working

gem uninstall pygments.rb --version "=0.5.2"  ; or whatever version you got installed
gem install pygments.rb --version "=0.5.0"

Failed to build gem native extension. or “python” is not recognized as an internal or external command, operable program or batch file.

“python” here can also be “ruby”, “gem” or “easy_install”, etc.

One of the reason of this error could be that your Ruby Dev kit binaries are not in PATH. Make sure that C:\devkit or whatever path you installed Ruby Development kit to is in path.

I make sure all the binaries of Ruby, Ruby Dev kit, Python are in path.

SET PATH=%PATH%;C:\ruby\bin;C:\devkit\bin;C:\git\bin;C:\Python\App;C:\devkit\mingw\bin

In Windows, you can also set PATH permanently by following the steps below

1. Hold Win and press Pause.
2. Click Advanced System Settings.
3. Click Environment Variables.
4. Append ;C:\python27 to the Path variable.
5. Restart Command Prompt.

If you get the following error with the –watch option

C:/Ruby193/lib/ruby/gems/1.9.1/gems/listen-1.3.1/lib/listen/adapter.rb:207:in `require': cannot load such file -- wdm (LoadError)

To fix that error, open the gemfile in your jekyll project directory and add these two lines:

require 'rbconfig'
gem 'wdm', '>= 0.1.0' if RbConfig::CONFIG['target_os'] =~ /mswin|mingw/i

UTF-8 breaks on windows

UTF-8 files have sometimes problems on Windows. To fix this error, either have your files in non-UTF-8 format or specify RedCarpet as your Markdown engine in _config.yml

# GitHub Defaults
lsi: false
pygments: true
safe: true

# UTF-8 & parse errors fix
markdown: redcarpet