Using Middleman to Build a Static Site

Using Middleman to Build a Static Site

Shittu Olumide Ayodeji's photo
Shittu Olumide Ayodeji
·

4 min read

Hello devs😎, Howdy. Today lets look talk about how to use middleman to build a static site.

Lets divide this tutorial into three:

  • Getting Started

  • Building a Site in Middleman

  • Templating and Blogging

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.

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

     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:

     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:

    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:

     activate :livereload

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

     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:

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

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

   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:

   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:

Check here for Youtube videos

Web Development