Lately I have been working a lot with YAML data in my HAML templates via Middleman. YAML is great for providing data to display on your site. It allows for easy modification and addition trough separate .yml files instead of having to copy-paste HTML/HAML. YAML is very intuitive to write and work with from Ruby (and templates). But if you are in need of some good documentation, check out this YAML Cookbook.
Static site development with Middleman
It’s great to use innovations such as CoffeeScript, Sass/Less and templating engines like Haml and Slim but they all need to be compiled in order to be understood by browsers. Command-line tools are provided but it can get tedious when working with multiple of these tools at a time. Building a huge rakefile might be a solution but it would be nice to have a flexible and ready to use solution, right? Luckily there is!
Enter Middleman: static site development at its finest. Middleman is static site generator based on Sinatra. It consists of a single command-line tool that watches a directory for changes and runs a server serving the compiled files.
Installing Middleman
To install Middleman and initialize a project:
$ cd my_project
$ gem install middleman
$ middleman init my_project --bundler --template=html5
I used two flags: --bundler creates a Gemfile containing a fixed version of middleman itself. --template=html5 adds HTML5 Boilerplate as a starting point. You can use the added index.html and style.css if you are OK with using plain HTML and CSS. I prefer HAML and SASS. You can drop in these HAML/SASSified versions of HTML5 Boilerplate I created. Or download the latest versions from this actively maintained Compass version of HTML5 Boilerplate at GitHub.
Start the server from the command-line:
$ cd my_project
$ middleman server
.. and open http://localhost:4567 in your browser.
Now just start developing your site! Any file you drop in your projects source folder will be automatically compiled by Middleman. The terminal will also notify you of any errors in your files.
Exporting your site
When you are done developing your site you will need to build it. Building means compiling all the source files for a production environment. This can be achieved by running the middleman build command:
$ cd my_project
$ middleman build
You will find the compiled site in the build folder.
Compressing assets
Middleman will optionally minify CSS & Javascript and compress images. You can enable these optimizations by editing the config.rb file to include the following lines:
configure :build do
activate :minify_css
activate :minify_javascript
activate :smusher
end
Smusher image compression requires for the middleman-smusher gem to be installed:
$ gem install middleman-smusher
If you’re using Bundler, just add gem "middleman-smusher" to your Gemfile and run bundle.
Automatic browser reloads with LiveReload
LiveReload is a Ruby gem and browser extension which automatically reloads your browser when you make changes to source files.
This is how to install it on OSX:
- Add
rb-fseventandguard-livereloadto your Gemfile - Run
bundle - Install a browser extension (Safari, Google Chrome, Firefox)
- Run
middleman server --livereload - If you’re using Safari, right-click the page and click ‘Enable LiveReload’
Your browser will now automatically reload upon file changes!
Follow the installation instructions on the LiveReload Github page for instructions on how to install on Linux and Windows.
Conclusion
Working with Middleman is a really pleasant experience. It definitely changed the way how I work on static sites. Its flexible system allows you to swap any templating or markup language and there are a whole lot of other features to discover like YAML data, templates & layouts and a ‘blog mode’. I tried a whole lot of other solutions like Nanoc and writing my own rakefiles, but in the end I definitely recommend Middleman. For more information, check out the excellent documentation over at middlemanapp.com.
