Middleman is awesome, bilingual support, ERB, and more ways to “hack”. The biggest commit in this migration was this:

100 changed files with 519 additions and 346 deletions

Including changes in post directory.

But I've got three more: one to fix /atom.xml, one to fix Disqus support, and the last one to remove files used only by Jekyll.

I met Middleman through Insiter's project, this is an event app, and you know, an event app does not require too much programming: you go there see the schedule, buy your tickets (usually this is another service) and go to the event, yey.

My first recommendation would be Jekyll, but it is for blogging not for event, if you need only one or two pages I really didn't know what you can use :/

Until now, as soon as I looked at Middleman's documentation I knew I would use that app.


Well, it will be really difficult (sorry about that)…

Before you start I suggest that you think twice, I only migrated because I tested in Jekyll and in Middleman bilingual support and in middleman it is a way better.


Like I said bilingual support was what couch me, not only creating two pages of the same content (For example: /about and /sobre) but also to use I18n as a centralizer of “static” content.

You can think I'm crazy: “I'm already in a static site”, what should I care about locale? When you start to repeat the same message again and again, you will be in trouble to update it. Using I18n you have the same message in only one place.

Despite bilingual support, I can tell you that using erb is better than using liquid. I don't know why jekyll's default templating is liquid but it is quite hard to work with. I've got more freedom to program erb.

You can have a lot of data in your website using Data Files. This is really awesome :)


Replacing liquid with erb is not difficult, I could have created a sed command to replace {{ with <%= and so on, but it is not that easy either. You will have some work to do (but it will be fun :).

Middleman does not have blogging feature built-in, you have to add a gem and configure properly. It is not difficult, but you will have to do.

Bilingual support is built-in, no gem required, but you have to activate it. If you get lost in the configuration (this is common in non-opinionated frameworks/software) just use the basic setup.


Read the official documentation first, it will be very helpful!

Start with a new project. The way that you choose to migrate depends only on yourself as a software architect.

If you choose to use the same directory, be sure to get everything committed.

Regardless of the way you choose, you will have to use middleman init command. In my case, because I didn't know how to use, it I used it twice. One for the general:

$ middleman init .

More info in Middleman: Starting a New Site.

Then I read the documentation and used it for blogging:

$ middleman init . --template=blog

More info in Middleman: Blogging.

Notice the ., I'm using the same repository.

WARNING: If you will have/migrate a blog use only the second one.

Everything else is about editing files…

File structure

I confess I did not like the _ in the begging of files while using Jekyll.

  • _config goes to config.rb and sometimes to data/ directory
  • _posts/ goes to source/posts/
  • Includes (aka, partials) from _includes/ go to source/ with the name starting with _
  • Your main layout goes from _layouts/default.html to source/layouts/layout.erb
  • If you active directory_indexes (See Middleman: Pretty URLs (Directory Indexes) you will have to rename files from, for example, about/index.html to source/about.html.erb

If you have read the previous topics you notice the change from liquid to erb. I don't recommend renaming files and testing if everything is ok.

Instead start by your home page, then move to posts and finish it with other parts, like contacts and feed.

After all changed you can have fun! For example in my previous site I hardcoded my social networks, in this one I created a file data/networks.yml wrote my social networks there and I created a loop to format them :)

In my case, I also created a section in each post called More posts in this series and References that things that I previously hardcode in the post itself are now configuration in the header of each post.