Geoffrey Wiseman

On Middleman

When I first started on the renovation for my personal site, I had intended to put it into Octopress. Its plain-text, markdown-aware model works well with me and it had the reputation for being more capable than Jekyll, which I've used on GitHub, while still being pretty simple to use. Before digging into Octopress, I built a static version of my site, both so I could post it and so that I knew what layout and content I wanted to put into Octopress. That could be seen as my mistake.

Octopress comes with a default template and a pile of useful capabilities -- Google analytics integration, site search, social sharing links, and so forth. If you're starting from scratch and you don't know what you have in mind, this lets you get started with a reasonably full-featured site without a lot of effort.

However, for my purposes, with a site design already worked out, each feature was something else for me to consider. Did I want to disable the social integration, or keep it? Did I have room in my header for the search box, and if not, where should I put it? Did I want their disappearing aside?

Add to this that it was my first time using Octopress and I found the internals fairly intrusive. The default configuration comes with a lot of files, in part to create a separation between the core files and the ones you should modify, which would allow you to update to a later version of octopress without overwriting your own data. But this meant that I needed to find the right file to make modifications, and I occasionally did things like make a CSS change only to have it overwritten by the site-building process shortly thereafter.

I didn't have a bad experience with Octopress, but I realized fairly quickly that I could either gut all the defaults and structure of Octopress, making it much harder to upgrade in the future, or I needed to take the time to learn its internals and adapt my design to its structure. I wasn't in the mood to shave any yaks, so I decided to take a quick look at the alternatives, including nanoc and middleman. After reading some opinions and taking a quick look at their introductory documentation, I decided that I'd give Middleman a shot before deciding what I wanted to do next.

Using Middleman

Getting started on Middleman was fairly easy; I had my general layout and page content adapted in short order. Getting the blogging extension setup was a little more work, in part because I hit an error and took a while to find its cause.

I'm fairly pleased with the quality and simplicity of Middleman, but there are two things that feel like they might still be a little lacking (bearing in mind that I've only been looking at Middleman for a few days).

Documentation

The documentation that's there seems clear and accessible, very legible and approachable. The documentation that's there isn't really the problem, it's just that the documentation is spartan. It's easy to see that something is possible with Middleman and then feel like finding out exactly how to do it is not covered by the documentation. For instance, when I read about templates, it was clear that Middleman had decent Markdown support, but that page doesn't describe exactly how to enable it or point to other documentation that does. It wasn't too hard to find some examples, but it would be nice not to have to find those outside of the Middleman docs.

You'll also quickly find that people writing about Middleman are often pointing out elements that they found lacking in the documentation in the hopes that it will help others, which is a good sign that there are holes in the documentation.

Again, it's not that the documentation is bad, just that it could be improved. I might try some pull requests on this front myself.

Community

The middleman forums don't seem very active. Maybe I caught it at a quiet time, maybe there aren't a lot of people using Middleman, or maybe the people who are don't like to gather together to talk about it. Whatever the cause, this means that getting answers to questions can take time, and may not find a response in a timeframe that you might like.

The forums seem to be down a lot. They don't seem to work on my iPhone. None of these are deal-breakers, but they aren't encouraging either.

Middleman vs. Octopress

Basically, if you're starting from scratch and you want something that comes with a lot of sensible defaults and a solid template that you can tweak, Octopress looks like a good way to get started quickly, and I feel like people who go that route are often happy with their choice.

On the other hand, if you already have a pretty good idea what you want your site to look like, Octopress isn't necessarily a bad choice, but you will have to take some time to figure out how your design and Octopress go together.

Middleman is a much simpler system with much simpler defaults and no real default template, AFAICS. On the other hand, it's a simple, easy-to-use system for quickly building out a generated static site from your own design and content, using things like markdown, coffeescript, sass and haml.

Neither one is right or wrong but perhaps one of the above descriptions feels more like what you're looking for. For me, Middleman was the right fit, at least for now.