Getting Jekyll setup on Windows 8
Jekyll, Ruby, Python, Pygments
In my last post, I started to get to grips with the Markdown syntax, aiming towards publishing my own website with these very blog posts on. I still feel very much in the dark as to how this is all going to end up, but, how else can I learn by doing?
I plan on using Jekyll - a tool for converting simple text to full "blog-aware" websites - to create a blog. (In fact, SPOILER ALERT : it created the very post you're reading!)
My first task is to try the Quick Start instructions from the Jekyll website. It promises to be "up and running in seconds", which is nice, but, as we'll see, it isn't that straightforward if you're new to this, like me, and, running Windows, like me...
Ruby
Jekyll is written in the Ruby programming language, which comes nicely preinstalled on OSx. That's nice, except, I'm running Windows 8... Some quick Googling and I end up with Ruby Installer for Windows. I install this, open up a new command prompt window and go for broke.
First problem - I need to tell Windows where to find the program I'm referring to when I type 'ruby'. If I don't, the command prompt has no idea what a command like 'ruby --version' is talking about.
More poking around online and I discover I need to edit the Environment Variables, specifically the PATH environment variable, which, as I understand it, tells Windows which files to look in for executable files that you try to call from the command prompt. Windows 8 makes it relatively quick to find anything, pushing the windows key and typing 'enviro' is enough to find the Edit system environmental variables setting. After adding the folder with the ruby executable file in (in my case 'C:\Ruby193\bin'), then restarting my cmd.exe I can now call ruby --version and see the version of Ruby I'm currently running.
Ok, not too difficult, but, something I've never done before.
Devkit
The next hurdle pops up almost immediately. Going back to the Jekyll homepage I obediently try the first line in the "Quick Start" section. Another error:
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'
Turns out that some Ruby extensions require the development kit to be installed in order to work correctly. No problem, download, extract and install the devkit. It can be found alongside the Ruby installer and the simple commands 'ruby dk.rb init' and 'ruby dk.rb install' should do all we need. This all worked pretty straight-forwardly for me, but, looking at other people's attempts, it doesn't necessarily go as planned and some poking around the config.yml file can be needed.
But not for me, Ruby AND the devkit now successfully installed.
Now, line 1 of the Jekyll Quick Start guide does what you'd expect, and I've successfully installed Jekyll!
Python and Pygments
As I plan on writing blogs with and about code, some syntax highlighting sounds nice. All I need is Python and Pygments.
I've got some experience of using Enthought Canopy to interact with and write for Python, and after installing Ruby, getting Python to work with my command prompt followed many of the same steps, including editing the PATH environment variable.
The next bit is where I started to get really confused.
Like a Version
Many of the components I've set up are the latest version available, as you would expect these will be the ones that work. That's just not true in this case. To get all the parts to play nicely together, it seems like you have to have particular versions. For example, pygments.rb 0.4.2 works well, but, version 0.5.0 doesn't. Finally, I got each piece in the puzzle in the right form, and assembled it all together. At first, it seemed to be working, but, bits wouldn't work the way you'd expect, for example the --watch flag, but, again, once all the programs involved were the right versions, it all finally clicked into place.
Get up and running in seconds...
...if you're running OSx.
Windows 8 can be set up to run Jekyll, but, for someone of my experience, it takes A LOT LONGER than seconds.
But, for now, I have Jekyll working and have managed to follow the "Quick Start" instructions and have Jekyll set me up a basic site directory and structure. Lovely.