Using Middleman to Build Your First Static Site

There are several static site generators that can help us quickly build and deploy static sites to the web within minutes. Middleman is one such static site generator that does the job with ease.

As a framework meant for modern web development, Middleman is a handy too that we can use to put together static sites as and when required. Built primarily on Ruby, Middleman is a popular web development choice for Ruby devs around the world.

In this article, we will be learning how to build our first static site using Middleman.

Getting Started

The first step, obviously, is to install and set things up before we can actually get started with Middleman. Since the framework itself is built on Ruby, we will need both the Ruby runtime environment and the RubyGems package manager installed beforehand.

On most Linux distros and Mac machines, Ruby runtime is bundled by default. For Windows, however, we might need to install it separately -- this can be achieved simply by using the RubyInstaller for Windows.

Once we have the Ruby runtime environment as well as RubyGems package manager set up, we can install Middleman as under:

default
gem install middleman

The above command will install Middleman, all of its dependencies as well as the command line tools for Middleman CLI.

That's all, we are now ready to get started with Middleman and build our first site using it.

Building a Site in Middleman

The first step is to create a separate directory for our project. The command that we can use is:

default
middleman init my_md_site

This will create a sub-directory my_md_site with the Middleman skeleton project. Basically, every project in Middleman is supplied with a standard web developmental skeleton, that has a predefined hierarchy of files and folders. An empty project will have a ./source sub-directory, where we will build our website. It will also have a config.rb file that will contain the settings and options for our Middleman site.

We can use a Bundler Gemfile for specifying additional dependencies, and also modify the structure of the JavaScript, images and other media folders (within the ./source directory) in our project to suit our needs.

Now, let us try starting the development engine. Essentially, Middleman strictly separates the production and development processes from each other. This means the majority of our time spent building the site will fall under the Development Cycle time.

Such methodology enables us to make use of tools such as JavaScript frameworks, libraries, HTML, SCSS, and more during the Development Cycle, but not during production.

To start the server, we will first navigate to our project directory, and then run the preview server command:

default
cd my_md_site

bundle exec middleman

The local server will start running at localhost:4567

Now, we can continue to work in the ./source directory that we learned about earlier. Middleman server will keep live reloading the page to help us preview our changes.

Perchance the changes are not reflected in real time, we might need to add the livereload extension to our config.rb file, as under:

default
activate :livereload

Once we are done with the development process, we can easily build our site to make it ready for deployment:

default
bundle exec middleman build

The above command will generate a static file for each file located within the source folder. Middleman will automatically clean up the build directory after it is done. For deployment, all the files will be in the ./build directory of our project. We can deploy as per our requirements -- either using the Middleman deploy command, or by any other preferred method.

Templating and Blogging

Middleman supports several templating languages that we can make use of. By default, it comes with support for ERB, HAML, SCSS as well as CoffeeScript, albeit we can enable other templating languages with the help of RubyGems.

The default templating language is ERB, which is pretty similar to HTML, but can also support loops, conditional statements, callbacks, and more. A complete list of all templating options can be found on this page.

Middleman has its own custom extension that can add support for blogging to our static site. In our gem file, we need to enable the extension as follows:

default
gem "middleman-blog", "~> 4.0"

Then, we can activate the above extension in the config.rb file:

default
activate :blog do |blog|
  # customize blog
end

For existing projects, we will need to re-run middleman init command to generate sample blog archives such as index of posts, tag index, date-based index, etc.

To add tags to an article, we just need to specify the same in the said article's Front Matter. For example:

default
---
title: Sample Blog Post
date: 2019/07/20
tags: blogging, example, samples
---
This is my blog post content.

Now, the above article or post will automatically be listed in the tag archives for "blogging", "example" as well as "samples".

Middleman's official YouTube channel has a useful video that explains how Middleman handles tags and taxonomies for blogs:

https://www.youtube.com/watch?v=4P1y67FvmHg

Conclusion

Middleman is a handy and useful static site generator that is used by quite a long list of folks, including MailChimp. As such, employing Middleman to build your static site can surely put you in good company.

With that said, Ruby is not the most popular web development language out there, and this is probably why Middleman does not really enjoy the level of popularity that can be attributed to certain other static site generators.

Nonetheless, Middleman is still a really useful tool, and for what it's worth, it can be a good solution for finally building that side project you always wanted to.

• Middleman Homepage
• Middleman on GitHub