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?
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.
Jekyll is a Ruby application. On windows, the easiest way to get Ruby is to use a windows installer.
- Installer for windows: http://rubyinstaller.org/
- Add Ruby executables to PATH during installation.
- I needed to restart windows at this point to be able to use Ruby.
- Test that ruby is installed correctly by running
ruby -vin a terminal. This returns the installed Ruby version number.
- Install the corresponding Ruby Devkit, also obtained from: http://rubyinstaller.org/
- 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/:
- Run in terminal:
gem install jekyll, this also installs a lot of Ruby “gem” packages needed for Jekyll.
- Install Rouge syntax highlighter:
gem install rouge
- Install wdm:
gem install wdm
gem update && gem cleanupregularly to keep your gems updated.
For some Jekyll themes you need to install bundler:
gem install bundler
- After installing your theme, navigate to its root directory and run:
- Generate and serve the theme on localhost by running:
bundle exec jekyll servefrom it root directory.
If the theme does not use bundler, you can generate and serve your site using:
- 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:
- Minimal mistakes
- Skinny Bones (Minimal mistakes is built on this).
- poole a base theme designed to be customized.
- Feeling Responsive
- Clean Blog
This site is currently based on Skinny Bones theme with the following modifications:
- Use rouge code highlighter:
Modifications to the site “Gemfile”
Added this code snippet (this avoids the polling “error message” when running
bundle exec jekyll serve on Windows):
if RbConfig::CONFIG['target_os'] =~ /mswin|mingw|cygwin/i
gem 'wdm', '>= 0.1.0'
Since I am not currently using Octopress, I commented out the line:
gem 'octopress', '~> 3.0.0.rc.12'