Static websites are extremely fast, quick to develop and highly scalable. Since static content remains constant it is easy to cache using CDNs. Deployment is simple and your site can even be hosted for free on GitHub Pages.

It is a good choice for projects that do not need on the fly generated content, like personal websites, blogs or landing pages. In this blog series I will describe how I built richardkall.se using one of the many available static site generators, Middleman.

Why Middleman?

There are plenty of static site generators out there, the most popular right now being Jekyll. There is even a list of the top open-source generators. I have tried a bunch of them over the years, including Jekyll, but I have always favored Middleman.

Coming from the Rails world I am familiar with the asset pipeline and Sprockets which Middleman also uses. It uses ERB as the default templating language and contains some of Rails view helpers, such as link_to and stylesheet_link_tag.

Middleman is well documented, has a great official extension for blogging and supports Compass and SASS out of the box.

Setting up the project

Middleman is a RubyGem which means you need Ruby and RubyGems package manager installed on your machine — these comes preinstalled with OS X. You also need Xcode (or just the Command Line Tools) which can be installed from the Mac App Store.

To install Middleman and the middleman-blog extension, run:

gem install middleman
gem install middleman-blog

Move to your projects directory and initialize a new project:

middleman init myblog --template=blog

This generates the following directory structure:

── myblog
   ├── Gemfile
   ├── Gemfile.lock
   ├── config.rb
   └── source
      ├── 2012-01-01-example-article.html.markdown
      ├── calendar.html.erb
      ├── feed.xml.builder
      ├── images
      ├── index.html.erb
      ├── javascripts
      ├── layout.erb
      ├── stylesheets
      └── tag.html.erb
  • Gemfile contains a list of all the gems you want to include.
  • config.rb contains all of Middleman’s configuration.
  • source contains all the source files such as articles, images, scripts etc.

Let us start the local server and see what we have so far:

middleman server

Creating your first article

As you have probably noticed, there is an example article located in the source directory. To create your own article, run:

middleman article "This is my first article"

This creates a new source file at source/YYYY-MM-DD-this-is-my-first-article.html.md. In the top section of the file you will find some frontmatter variables (date, title etc.). You can start writing your post below these, using Markdown syntax. Middleman will automatically convert the content to plain HTML.

LiveReload

Middleman has a official extension that will refresh your browser window every time you make a change in your site directory. To use this feature, open config.rb and add this line:

activate :livereload

Then restart your local server. Press Ctrl + C to shut down if the server is still running.

Building the static files

When you are ready to publish your website, you will need to generate the static files. Run the following command in your project directory and Middleman will take care of the rest:

middleman build

This will create a build directory in your project, containing the compiled files. You do not have to clean this directory each time, this is handled automatically.

Part one describes the very basics of Middleman and how to create your first project. In the coming posts I am planning to cover areas such as deployment, configuration and extensions.

The source code for richardkall.se is available on GitHub.