It took me almost a year, but with the release of Octopress 3, I’ve finally had an option to get this blog back into a functional state. With the scheduled discontinuation of WebINK on 30 June 2015, my deadline had been set.

The version 2 release of Jekyll has finally modernised the static page generator that this blog currently runs on, and it now runs on the latest version of Ruby (currently version 2.2.2).

There were a few challenges for a straight-out migration. Some older plugins and liquid tags are no longer supported, but some much sought after features are now built-in.

Rack App

With the new version of Jekyll, the project folder is not pre-configured to run as a Rack app. The config.ru supplied by the previous Octopress installation is too full of cruft and now would be a perfect time to improve it.

To serve static pages from a folder, Rack has Rack::Static that can be used directly. Unfortunately, it does not have automagic support for returning a custom error 404 page for file-not-found errors.

Fortunately, Vienna can be used (almost) out-of-the-box for this. The default is to serve files from a public directory, but for Jekyll, the generated site is found under _site. For the file-not-found custom error page to work, a 404.html needs to be generated within the _site directory.

My config.ru now contains only 2 lines of Ruby code:

#!/usr/bin/env rackup
#\ -E deployment

require 'vienna'
run Vienna::Application.new('_site')

Include the following in your Gemfile:

gem 'rack'
gem 'vienna'

Done! To test this our, run rackup in the project directory, and Rack will spawn a webserver to serve contents from the _site folder.

Push to Heroku and it will work. Include a Procfile if you want a custom webserver, such as Rainbows!.

Incompatible Change

The biggest incompatible change that I could not workaround and had to edit every of my affected posts was the removal of include_code liquid tag. Fortunately, render-code solves the same problem with a minor change in function name. A quick find-and-replace or sed solved it.

Local Search

With the new Jekyll theme, there is no search engine configured for the blog. I used Google’s Custom Search Engine with a 2-page layout for this and installation was a breeze.

Basically, I embedded a custom searchbox on the top right menu, and added a search.html that the searchbox will POST to.

Create a search.html in the project directory with the following:

---
layout: page
title: Search
permalink: /search/
---
<gcse:search>

Then within the header, implement a form with a textbox and POST to /search/ with q as the query parameter.

Finally, include the Google-supplied JavaScript code into the header or footer of the site.

Done!

Jekyll Plugins

Here are the list of Jekyll plugins that I currently use within my Gemfile:

group :jekyll_plugins do
	gem 'octopress-filters'
	gem 'octopress-include-tag'
	gem 'octopress-minify-html'
	gem 'octopress-gist'
	gem 'octopress-solarized'
	gem 'octopress-codefence'
	gem 'octopress-render-code'
	gem 'octopress-linkblog'
	gem 'octopress-feeds'
	gem 'octopress-littlefoot'
	gem 'octopress-image-tag'
	gem 'octopress-return-tag'
	gem 'jekyll-assets'
end

Your mileage may vary, but this should be a good starting point.