Update: If you would like to directly download the portable version of Jekyll. See my new blog post here
Update (26/06/14): This article is bit outdated and no longer deemed official instuctions to get Jekyll running on Windows. Please see this article for more updated and authoritative source of instructions.
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
- Python : I strongly recommend using 2.7.5 as opposed to version 3. I used the portable version available here
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
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
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.
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
Now browse to http://localhost:4000
##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:
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
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
##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.
In Windows, you can also set PATH permanently by following the steps below
- Hold Win and press Pause.
- Click Advanced System Settings.
- Click Environment Variables.
- Append ;C:\python27 to the Path variable.
- 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:
##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
# GitHub Defaults