Moving to Middleman

My previous personal site was a simple HTML/CSS web page that I put together as a quick overview of some small projects I was working on. Recently, I decided to start up a blog to document coding experiences and put myself out there in the tech community. I wanted to use a static site generator to run my blog and I only had two real requirements:

  1. Write markdown for the actual blog posts
  2. Ruby-based

I quckly narrowed down to two options: Jekyll and Middleman; two of the most popular Ruby static site generators. I had dabbled with Jekyll a little in the past, but the real reason I chose Middleman was because a) I had recently listened to a podcast with the maintainer and b) I decided I would prefer writing my templates with ERB instead of Liquid.

Getting Started and Blog Setup

The base theme of this site I shamelessly pulled from Poole, an open-source foundation template. Ironically, both Poole templates are for Jekyll, but I converted them to ERB for use with Middleman (with some of my own tweaks of course). I really like @mdo's CSS work and it helped get things off the ground quickly.

Middleman makes it really easy to setup a blog with the middleman-blog extension. I made a quick blog and used almost all of the default settings of the blog extension.


One of my goals when creating this new site was to make it easy to add new items to the portfolio page without writing any new HTML/CSS.

With Middleman, I was able to use the data files feature to separate the content from the structure. I had two types of portfolio entries: mobile apps and web projects. I created layouts for each type and added a property in the data file to distinguish between the two. Now, to add a new item to the list, I only have to add a new entry to the data file. Very easy.


For SEO reasons, I decided to write unique descriptions for all my pages and blog posts. I only have a few pages so the overhead to write descriptions is low. For the blog posts, I could carefully write the first few sentences for each post and let Google generate the descriptions, but again, because it's so easy to do it myself, I prefer complete control.

I also wrote a few simple helpers to pull this description data from the page and post frontmatter.

def page_title ? '...' :

def page_description

There are a few other small things I'd like to change, but overall I had a very pleasant experiance with Middleman. The one thing that bothers me is not knowing what data/helpers are available on each page. For example, what is the difference between current_page and current_article, what properties are in each object, and in which cases are they nil? Usually this led to some trial and error and reading the Middleman source code.

Note: I setup this site before Middleman v4 was released and used Middleman v3.4

Links I Found Helpful