Jekyll - my experience

This post contains a pseudo random collection of links and notes about getting a Jekyll site up and running. I am writing and updating this as I learn, primarily for my own use and reference, but maybe you will find it useful too?

The site is edited with Notepad++ and generated on a Windows 8 PC. I am an experienced Python programmer, but with no previous Ruby experience.

Jekyll uses Ruby to generate your site from kramdown formatted text files, a superset of Markdown. The generated site is entirely contained in a _site folder including all css and js files, images, posts and pages in html format.

After installing everything (see below), you add and edit kramdown formatted text files locally on your PC to generate your site content. You also add images etc. locally, these are all placed in your theme folder with sub folders. While working on your site, you can run a special Jekyll process on your PC that instantly detects changes and serves a updated site on localhost to immediately show your latest site edits as soon as you save a new or updated Markdown file in your _posts folder.

After each regeneration, the _site folder contains your complete generated site, ready to upload to your web server.

Installing Ruby and Jekyll on windows

Jekyll is a Ruby application. On windows, the easiest way to get Ruby is to use a windows installer.

  1. Installer for windows: http://rubyinstaller.org/
  2. Add Ruby executables to PATH during installation.
  3. I needed to restart windows at this point to be able to use Ruby.
  4. Test that ruby is installed correctly by running ruby -v in a terminal. This returns the installed Ruby version number.
  5. Install the corresponding Ruby Devkit, also obtained from: http://rubyinstaller.org/
  6. Bind the Devkit to the Ruby installation: Follow the instructions on: http://jekyll-windows.juthilo.com/1-ruby-and-devkit/

Jekyll is a little more work to install on windows. I followed the excellent guide at http://jekyll-windows.juthilo.com/:

  1. Run in terminal: gem install jekyll, this also installs a lot of Ruby “gem” packages needed for Jekyll.
  2. Install Rouge syntax highlighter: gem install rouge
  3. Install wdm: gem install wdm
  4. Run gem update && gem cleanup regularly to keep your gems updated.

For some Jekyll themes you need to install bundler:

  1. gem install bundler
  2. After installing your theme, navigate to its root directory and run: bundle install
  3. Generate and serve the theme on localhost by running: bundle exec jekyll serve from it root directory.

If the theme does not use bundler, you can generate and serve your site using: jekyll serve

Some tips:

  • Ensure that your kramdown files are saved in UTF-8 encoding without BOM.
  • Ensure that your kramdown files are saved with .md or .markdown extension. Any *.txt files will be served without any formatting!

Interesting Jekyll themes

My personal short list of minimalistic Jekyll themes:

Theme modifications

This site is currently based on Skinny Bones theme with the following modifications:

_config.yml file:

  • Use rouge code highlighter: highlighter: rouge

Modifications to the site “Gemfile”

Added this code snippet (this avoids the polling “error message” when running bundle exec jekyll serve on Windows):

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

Since I am not currently using Octopress, I commented out the line:
gem 'octopress', '~> 3.0.0.rc.12'