Migrating from StaticMatic to Middleman

One of my sites (krasotki.dp.ua, which is in Russian – sorry) is (was) built around Staticmatic, which is (again, was) a convenient tool to make static sites with modern-day conveniences such as partials, helpers, and using a templating language such as Haml.

Anyways, Staticmatic was getting kind of old — the latest version has been released a year and a half ago — and I set out on a search for a better static site generator. Jekyll — the popular choice — has a very strong inclination towards blogs and while it’s possible to do a non-blog site using Jekyll, it still feels unnatural.

Meet Middleman

Middleman is a modern and well-designed static site generator which borrows many conventions from Rails.

What I liked about Middleman is that all the hacks I’ve been piling up on top of Staticmatic are already built in: a Yaml-based sort-of-database — some data is far easier to edit in Yaml than in page source, custom build steps — I’ve been using those to generate a PDF version of the schedule, built-in Sass compilation and so forth.

Porting a site from Staticmatic to Middleman

Initial setup

• Install gem (gem install middleman).

• Create a new catalog, then run middleman init there; this will create the scaffolding. Immediately purge the source catalog — we’ll be filling that one manually.

Site contents

The main difference between Middleman’s and Staticmatic’s directory layout is that Middleman puts the entire site into the source directory, instead of splitting it up into pages, partials, etc. Thus we combine various subdirectories of src from the old app into source:

• site contents (images, stylesheets, static files) are copied over directly to source.

• src/pages — copy to source, rename .haml to .html.haml (page.haml becomes page.html.haml)

• src/partials — copy to source, add underscore before name (partial.haml becomes _partial.haml)

• src/layouts — also copy to source; the default layout, called default.haml in Staticmatic, is now called layout.haml.

Built-in helpers

Middleman uses Rails-style view helpers, and Staticmatic uses custom ones. This means you’ll have to fix your views manually, replacing link with link_to, img with image_tag, and so on. Here’s a list of StaticMatic helpers and here are Middleman helpers.

If that’s too boring for you, you can define a custom compatibility layer, implementing Staticmatic helpers with Middleman helpers. I bet this will take more time than a search-and-replace.

Custom helpers

Helpers from src/helpers should be moved to lib in the new app, plus you’ll need to explicitly mention them in config.rb:

require './lib/foo_helper'
helpers FooHelper

Finishing up

I suggest deleting everything from the old Staticmatic directory, and moving over the newly ported application there. If you’re using version control, that is, and if you’re not, switching engines is a very appropriate time to start.

Bonus: deploying Middleman with Capistrano

Protip: though Capistrano creates config/deploy.rb when you run capify, you don’t need it. Capistrano works perfectly fine with a single Capfile containing the entire deployment configuration.

So create a Capfile in the app’s root and put this code inside:

load 'deploy' if respond_to?(:namespace) # cap2 differentiator

set :application, "YOUR_APP_NAME"
set :deploy_to, "/PATH/TO/APP/ON/SERVER"
set :deploy_via, :copy
set :repository, "build" 
set :scm, :none 
set :copy_compression, :gzip
set :use_sudo, false
set :domain, 'YOUR_APP_DOMAIN'
set :user, 'YOUR_DEPLOY_USER'

role :web, 'YOUR_APP_DOMAIN'

before 'deploy:update_code' do
  run_locally 'rm -rf build/*'
  run_locally 'middleman build'
end

That’s all!