Generating a Blog with MiddleMan
Thanks to Jekyll and some similar technologies, static site generators have recently made a comeback. Static sites have distinct advantages when it comes to cloud computing: They have simple requirements (static web server), consume small amounts of resources, and can be hosted out of object storage at extremely low cost.
MiddleMan is a generic static site generator. Rather than focusing only on blogs, as Jekyll does, it provides the basic facilities for building any type of site. Extensions extend MiddleMan by providing specific features. The architecture is elegant and easy to use.
In this article, I show how to create a simple blog using MiddleMan (and it's blog extension). <!--break-->
Installing
I'm starting with a basically configured Ruby environment on Mac or Linux. Using gem, we can install the MiddleMan package and the blog extension:
$ gem install middleman middleman-blog
Once the installation is done, you should be able to run middleman --help on the command line.
From here, we can start a new project like this:
$ middleman init MyProject --template=blog
$ cd MyProject
Looking around in this newly created directory, we can see the basic infrastructure of the site.
Since we're creating a blog site, let's go ahead and install the blog-specific extensions to MiddleMan. To do this, we can edit the Gemfile file to look like this:
source :rubygems
gem "middleman", "~> 3.0.13"
gem "middleman-blog", "~> 3.2.0"
gem "middleman-syntax", "> 0.0.0"
gem "builder", "~> 3.0.0"
gem "nokogiri", "> 0.0.0"
gem "redcarpet"
This adds support for creating summaries (nokogiri) and syntax highlighting (middleman-syntax and redcarpet). The remaining lines should have been there already, as they were created during initial installation.
Running bundler install will install all of these dependencies.
Finally, we need to make a few changes to config.rb. I added the following lines to my config.rb:
activate :syntax
set :markdown_engine, :redcarpet
This activates syntax highlighting using the redcarpet markdown converter.
Starting a Dev Site
Now we can start up a local dev server to test out the new site:
$ bundle exec middleman server
This will create simple web server listening on http://localhost:4567. Pointing your browser at that site should bring up a vanilla index webpage.
Leave this task running in the background during local development. You can stop it at any time with CTRL-C.
From there, we can edit the site.
Editing the Site
The entire site source is inside of the source/ directory in the project. MiddleMan uses Ruby erb templates. We can begin by editing the index.html.erb file. Any modifications made should show up immediately on the locally running dev site.
To create a new blog post, run this command:
$ middleman article "First Post"
This will create an article in the source folder. By default, it should be named something like 2013-04-26-first-post.html.markdown.
The new page should look something like this:
---
title: First Post
date: 2013-04-30 15:26 UTC
tags:
---
This is just YAML front matter, which MiddleMan uses as site metadata (for things like building lists of articles).
Underneath the YAML header, we can write an article in Markdown and HTML:
---
title: First Post
date: 2013-04-30 15:26 UTC
tags:
---
## Hello World
This is markdown text.
Once this file is saved, you can reload the site in your browser and see a link to the new article.
From here, you can begin building up the content and the design for your MiddleMan site.
Exporting the Site
At some point we want to be able to export the entire site into static resources so that we can upload them.
This is done with the following command:
$ bundle exec middleman build
This will export the entire site into the build/ directory.
