Migrating ObjColumnist.com from Wordpress to Middleman

A few months ago I decided to migrate ObjColumnist.com from a custom Wordpress install to a Middleman generated static site. I thought I would document my thinking process about undertaking this migration and how it turned out.

I should start by saying that I have nothing inherently against Wordpress (although I admit I’m not the greatest PHP or MySQL fan), but it was in fact Wordpress’s extensive flexibility that lead me to move away from it. Wordpress in 2017 is so much more than a blogging platform, its essentially a constantly evolving, highly customisable CMS that has numerous Themes and Plugins. The truth is, as a solo blogger I don’t need any of Wordpress’s advanced functionality, I didn’t even need comments! Moreover installing a Wordpress theme is trivial, but to customise it? I didn’t even know where to start!

This meant that the requirements for my new site were:

I had a preference for a Ruby based static site generator, which naturally lead me down the route of Jekyll. The one area that I found Jekyll fell down on was the ease of theming, it’s theming is comprehensive but overkill and too complex for my needs.

I then took a look at Middleman, which is another static site generator written in Ruby, that has an official blogging extension. The blogging extension did exactly what I wanted, it generated a blog from a folder full of Markdown files (one for each blog post, or what Middleman refers to as articles) and also supported all of the more programmer centric Markdown features that I had become accustom to when using GitHub, such as language specific code fences. Middleman also forced me to use my own styling.

Here is an example of one of the Markdown files that can be viewed here (note that I have left the “tags” metadata in, even though I currently don’t make use of them on the site):

---
title: WWDC 2015 Review
date: '2015-06-13 11:38:06'
tags:
- opinion
---

Users and Analysts have finally got what they wanted this year, as both iOS and OS X are receiving a "Snow Leopard" like update. This will allow developers (including Apple's) to iron out the rough edges in their apps but still add a sprinkling of new features.

My original reaction to the Keynote was that I found it somewhat underwhelming, but in hindsight after watching the sessions, I've come to the conclusion that there are a lot of small and useful improvements that I can't wait to make use of in my own apps.

I personally didn't attend WWDC or any of the alternative conferences in San Francisco this year, but found the live streaming of sessions great for keeping up to date. It also increased the level of discussion and sense of community between fellow developers.

From watching the sessions and the keynote, its safe to say the following 3 points are going to be important things to think about going forward:

## Swift

Swift is the language that you should now be using to develop apps for Apple's platforms going forward. Personally I am not planning to rewrite any of my apps using Swift, but will be using it for any new apps that I create going forward. Swift 2 is a great update to an already great language (although there is still a long way for the tools to go). I also noticed that when Apple pointed out problems during the sessions they were often written in Objective-C, while the solutions were in Swift. I don't think that these subtle hints were by accident. Developers may take time to adjust to Swift's "Protocol Oriented" approach, but I feel it will be worth it it.

## Adaptivity

Apple have introduced numerous APIs over the last few years such as AutoLayout and Size Classes to support designing your UI for multiple window sizes. I say window sizes, as screen sizes don't matter anymore and you shouldn’t — can’t — make any assumptions based upon screen sizes, device model or orientation. This unfortunately may mean we see a reduction of bespoke iPad UIs, but maybe this is the price we have to pay for adaptability.

## Search and Deep Linking

Apple made a big deal about search in the Keynote and iOS 9 will allow developers to index their data so it appears in search. Apple has also introduced universal links, which allows apps to intercept and handle HTTP(s) URLs for their website with their app. Both of these changes mean that apps will also need to support "Deep Linking". This will probably end up being one of the more complex features for developers to implement this year, as apps must be able to present linked content regardless of the apps current view hierarchy.

## Privacy

Apple's common theme at the moment is privacy and this is reflected in iOS 9s API changes. NSURLSession now requires a secure connection by default and apps can no longer use URL Schemes to see what apps are installed on a device. We as developers should take note of this, and continue to keep user’s information secure e.g making sure user data is encrypted, storing passwords using Apple's Keychain APIs etc.

Those were my major takeaways from the conference and with iOS 9 and OS X 10.11 scheduled to be released in just a few months time, I better start coding ...

The entire migration of Wordpress to Middleman (including building the Middleman site from scratch) took about 5 hours. I used wp2middleman to export my Wordpress posts to Markdown files. Everything exported correctly, but I noticed lots of inconsistency in emphasis and headings throughout the files (which was my fault!), so I spent about an hour cleaning up all of the files so that they were consistent.

The Middleman side of things was trivial, but I still probably spent around 1 hour setting up the template and config files so that the produced site was exactly what I wanted.

This included:

My Gemfile ended up as:

source 'https://rubygems.org'

# Middleman Gems
gem "middleman", "~> 4.1"
gem "middleman-blog"
gem "middleman-syntax"

gem 'redcarpet', '~> 3.3', '>= 3.3.3'
gem 'middleman-google-analytics', '~> 2.1'

# For feed.xml.builder
gem "builder", "~> 3.0"

My config.rb file ended up as:

###
# Page options, layouts, aliases and proxies
###

# Per-page layout changes:
#
# With no layout
page '/*.xml', layout: false
page '/*.json', layout: false
page '/*.txt', layout: false

###
# Helpers
###

activate :blog do |blog|
  blog.permalink = "{year}/{month}/{day}/{title}.html"
  # Matcher for blog source files
  blog.sources = "{year}-{month}-{day}-{title}.html"
  blog.layout = "article"

  blog.tag_template = nil
  blog.calendar_template = nil

  blog.generate_day_pages = false
  blog.generate_month_pages = false
  blog.generate_year_pages = false

  blog.generate_tag_pages = false

  # Enable pagination
  blog.paginate = true
  blog.per_page = 10
  blog.page_link = "page/{num}"
end

page "/feed.xml", layout: false

# Enable pretty urls
activate :directory_indexes

###
# Google Analytics
###

activate :google_analytics do |ga|
  ga.tracking_id = "UA-MYTRACKINGID"
end

###
# Markdown configuration
###

set :markdown_engine, :redcarpet
set :markdown, :fenced_code_blocks => true, :tables => true, :smartypants => true, :autolink => true, :highlight => true, :with_toc_data => true
activate :syntax

###
# Build specific configuration
###

configure :build do
  # Minify CSS on build
  activate :minify_css

  # Minify Javascript on build
  activate :minify_javascript
end

The last 3 hours was spent implementing the site itself, and besides the few inevitable head scratching moments with CSS this went as smoothly as could be expected.

Deployment was a case of building the blog and uploading it to my server. The site has no dependancies as it is just static files.

In hindsight I’m really happy that I decided to migrate my blog from Wordpress to Middleman. The site looks better, loads faster, and it is now trivial for me to make any changes. Moreover I don’t have to deal with installing updates or fixing any issues that come up with upgrading Wordpress or one of its Themes or Plugins. Obviously I could of achieved this with one of the other static site generators, or doing it all by hand, but I can whole heartedly recommend building your static blog using Middleman.