Blog migration: From Jekyll to Middleman

1st November 2015 – 722 words
Ups I did it again.

Throughout the history of this Blog, I’ve come across several different Blogging engines. Usually, I could migrate all my previous posts without too much problems from one engine to the next. As I recall, I have used:

Now, I’ve migrated my Blog from Jekyll to Middleman, a different static site generator.


Using Jekyll was fine most of the time, but I had these issues:

First, I noticed a major speed issue, if you have more than a couple of blog posts. Reloading a post after editing the text file took nearly 1-2 minutes for a full refresh - with only 270 blog posts as of today. This is due to the architecture of Jekyll, that always makes a full run. This increases the feedback cycle, especially when (re)-formatting posts or add custom elements. The proposed “fix” from Octopress/Jekyll is, to remove all your other posts from the directory for the time of writing -.- Now, with middleman, the wait time is down to 1-2 seconds with all the features I had with Jekyll (similar posts, prev/next posts, categories, …).

Second, as a Ruby developer, having to use Liquid text instead of just dropping to Ruby any time I need, is cumbersome. For custom elements, I had to create my own Liquid blocks. Now, with Middleman, I am happier than before. I can use templating languages like Slim/Erb and access the Asset Pipeline from Rails (sprockets). Being able to use Ruby, I can also utilize the awesome Pry debugger any time I am unsure what functions and variables are available in a specific scope.

Middleman also ships with a routing page, that you can access in development: localhost:4567/__middleman/sitemap shows all files that Middleman will generate. Besides, there are great plugins, like:

  • middleman-blog - essential
  • middleman-livereload
  • middleman-deploy - Can deploy to Rsync, FTP, Github-Pages or AWS.
  • middleman-imageoptim - Automatically reduce file sizes of images
  • middleman-blog-drafts convenience commands for creating articles that take some time to write


Both Jekyll and Middleman use just plain text files, like Markdown/Textile/HTML + a YAML frontmatter. So migrating just consisted of copying over and running a few sed scripts to replace the custom liquid tags and migrate some of the YAML frontmatter tags.

# OSX sed
sed -i "" 's/language: english/lang: en/g' $*
sed -i "" 's/language: german/lang: de/g' $*
sed -i "" 's/categories:/tags:/g' $*
sed -i "" 's/{% *blockquote *%}/<blockquote>/g' $*
sed -i "" 's/{% *endblockquote *%}/<\/blockquote>/g' $*

# sed syntax from OSX doesnt support alternatives, so install gsed
# if you are on Linux just use sed :)
gsed -i 's/{% img \(alignright \|alignleft \|left \|right \|\)\([^ ]\+\) \(.*\)*%}/<img src="\2" class="\1" title="\3"\/>/g' $*
gsed -i 's/{% toc %}/&lt;toc><\/toc>/g' $*

Middleman crashes, if the date in the YAML front matter does not matched the filename. So, I fixed all blog posts with problems manually:

#print out all deviant posts
echo 'puts Dir["**/*.md"].select{|i| a, b = [[/date: "?(\d\d\d\d-\d\d-\d\d)/, 1], i[/\/(\d\d\d\d-\d\d-\d\d)/, 1] ]; a != b }' | ruby

Besides this, I could add all features from my previous setup, including:

  • Tagging / Categories
  • Similar posts → Which posts have the most tags in common
  • Disqus comment thread (make sure the URLs stay the same)
  • Table of contents → Using custom JavaScript
  • Syntax-Highlight. Before, I used Pygments but I switched now to client side rendering with HighlightJS. Unfortunately, YAML highlighting is missing.
  • Feeds / Sitemap.xml

I’ve added:

Page speed result page - everything green

  • A new design, Carte-noire from a Jekyll theme which is fully responsive
  • Passing Google-Page Speed test - Everything should be great on mobile now!
  • search, implemented with JavaScript, by creating a search.json at build time with all posts + search tokens in it (Jeykll-Search)
  • Multiple authors possible. I have one or two old guest posts, that I might reassign