The Middleman. A modular, feature-rich static site generator
The two most common approaches I've encountered are to develop every page statically with shared components repeated in each and every file. Alternatively, many developers assume global familiarity with PHP or ASP and use some form of Server-Side Include for shared components. The situation gets a bit trickier for global constants and shared paths. I've seen PHP variables scattered throughout a site. I've also seen IDE-specific includes (like Textmate's) used for shared content and variables.
These approaches have a couple problems. First, they assume the client cares what technology you use. Second, they require you to deploy the site to a web-server before the client can preview the design. And finally, the backend team will probably be frustrated with your PHP unless they just so happen to use it as well.
The Ruby world already has a handful of tools which accomplish this. The two most common, in my opinion, are StaticMatic and Nanoc. I have far more experience with StaticMatic so I'll talk about that first.
StaticMatic is heavily inspired by Ruby on Rails and performs it's task in a similar, but still slightly different, way. I've used StaticMatic for years, contributed to it's codebase and converted anyone who would listen to using it. It allowed me to use Haml & Sass in static pages and I loved it. However, I have my own opinions and StaticMatic does a lot of little things differently than I'd like. Rather than fork that project or complain online, I wrote my own replacement which fits my style of development more closely. Apples and oranges in my opinion, but maybe other developers will be more at home with Middleman, like I am.
Nanoc, on the other hand, looks very, very powerful. Unfortunately, I've been frequently overwhelmed by the documentation and feature set. Like I said above, I'm scratching my own itch and Nanoc provided a lot more than I needed while requiring a lot of Ruby-writing to work with. I see Middleman as the Sinatra of the static deployment world. There are bigger, and arguably better, systems out there, but my niche is small, easy to learn and fast.
The best way to describe Middleman is to show you how I use it. I'll show you how to install it a little further down. The mm-init command takes a single argument, the directory which will contain your new project. If I run that command from the terminal, I will get the following:
The initializer creates a homepage (index.html.haml), a layout to contain shared interface elements and a site-wide stylesheet. As you can see, Haml and Sass are the default templating languages. However, you're free to replace .haml with .erb and use Erb templates or enable additional renderers like Markdown (more on this later). The Sass support comes with Compass bundled to provide a large number of css frameworks such as YUI, Blueprint, 960.gs, Susy and more.
The init.rb file allows customization and enabling or disabling specific features. The default init.rb looks like this:
# Helpers helpers do end # Generic configuration # enable :slickmap # Build-specific configuration configure :build do # For example, change the Compass output style for deployment # enable :minified_css # Or use a different image path # set :http_path, "/Content/images/" # Disable cache buster # disable :cache_buster end
Helpers are functions which can be called from your templates and allow you to abstract frequently repeated code. Middleman comes with a handful, most for asset management, but you can write your own within the helpers block in the init.rb.
Next is the commented-out Slickmap feature. If you remove the comment, your structure will be parsed and a sitemap will automatically be generated for you. There are many other features you can enable or disable and this is the place to do it.
Finally, there is the configure block which allows variables, helpers and features to be modified only during the final static HTML build process. The example init.rb offers css minification, cache busting and changing the location of your assets in production (if you're using a CDN).
Configuration & an Example
The mm-init command creates an init.rb which will contain your customizations and configuration.
As you can see, the basic project is quite sparse and you get to choose which features your project needs. The current list of features is as follows:
More documentation on these features and what they enable can be found on the project website.
So, the quickest way to get started is to run mm-init and point it at a location for your new project. Then change directories into that project and run mm-server. Now you can develop your site and preview the results on localhost:4567. Finally, when you're ready to deliver raw HTML, run mm-build from the project folder. Here's an example.
Source & bug reports
The code, as always, is on GitHub at: http://github.com/middleman/middleman.
There is also a wiki at: http://wiki.github.com/middleman/middleman.
And finally, please report bugs to: http://github.com/middleman/middleman/issues.