Category: middleman

Learning – Middleman – Static Site Generator

Learning - Middleman - Static Site Generator


  • Install Ruby
ruby --version
  • Install middleman
gem install middleman
middleman version

Install on Mac

Install xcode on Mac

xcode-select --install

Fix version issue in Mac

If encounter error on Mac indicating version low, run following command to install ruby version manager

curl -L | bash -s stable

Restart terminal and run following command

rvm install ruby-2.4.2
rvm --default use ruby-2.4.2
ruby -v

Creating a site

middleman init ga_site

Then a folder called ga_site is created.


middleman server

Access website via http://localhost:4567


source/layouts/layout.erb - default layout
source/index.html.erb - default home page

Activate LiveReload

LiveReload is able to reload the pages when they changed.

In config.rb file, add following line.


activate :livereload

In Gemfile, add following line

gem 'middleman-livereload'

In project file, run following command

bundle install middleman-livereload

Restart middleman server

middleman server

Create html file ga_site/source/a.html.erb or ga_site/source/dir1/b.html.erb, then can access file from browser.

Note: If use .html without .erb, then it will not use default template.

Create markdown file as ga_site/source/

Front Matter

Front matter can use JSON or YAML


title: Middleman is Running
author: "Mike"


"title": "New Title"

Access front matter variable

<%= %>


All pages are using source/layouts/layout.erb to display erb files. So, can modify the layout.erb file to change layout.

Helper Methods

Helpers are small codes can be used in markdown file.

<%= link_to 'Giraffe Academy', '' %>

To include ga_site/sources/styllesheets/ga_style

<%= stylesheet_link_tag 'ga_style' %>

To include ga_site/sources/javascripts/ga_code.js

<%= javascript_include_tag 'ga_code' %>

To include ga_site/source/images/log.png

<%= image_tag 'logo.png' %>

Other helpers can be found in


Default layout

The file ga_site/source/layouts/layout.erb is for all pages.

Specific layout

Create another layout2.erb file, then can be used in other markdown file using front matter as below a.html.erb.

layout: layout2

This is a.html

Layout for one directory

If want to specify all files in one directory use specific layout, can configure in config.rb file as below.

page '/dir1/*', layout: 'layout2'

Wrap layout

For example, the layout2 needs to use default layout and wrap it around, can be defined in layout2.erb file

<% wrap_layout :layout do %>
  New Layout <br> <hr>
  <%= yield %>
  <br><hr>New Layout
<% end %>


  • Create a folder ga_site/source/partials/, this is not mandatory.

  • Create partial file called _header.erb file, the leading _ is mandatory.

<h1>This is the Title</h1>

To include in layout.erb file,

<%= partial 'partials/header' %>

Note: the leading _ and the tailing .erb are not shown in this statement, middleman knows how to find the file.

Passing variable

In layout.erb file

<%= partial(:'partials/header', :locals => { :title => 'My Title', :color => "blue" })

In _header.erb file

<h1 style="color: <%= color %>"><%= title %></h1>

Data Files

Create a data folder as ga_site/data, create data file can be YAML or JSON files. For example test.yml

dog: "Golden Retriever"
  - Tooth Brush
  - Shampoo
  - Soap

In layout.erb or index.erb file

<%= %>


<% data.test.products.each do |f| %>
  <li><%= f %></li>
<% end %>

If Statement

<% if == "A" and %>
  This is the A file
<% elsif == "B" %>
  This is the B file
<% else %>
  This is not A or B
<% end %>


In layout.erb file

<% sitemap.resources.each do |f| %>
  <% if f.content_type.include? "html" %>
    <% %> <br>
    <% f.path %> <br>
    <% f.content_type %> <br>
    <li><a href="<%= f.path %>"><%= %></a></li>
  <% end %>
<% end %>


<% %>

<% current_resource.siblings.each do |f| %>
  <% %> <br>
<% end %>

<% current_resource.children.each do |f| %>
  <% %> <br>
<% end %>

Building a Blog

First install blog generator

gem install middleman-blog

Initialize blog site

middleman init myBlog --template=blog

Start middleman blog server

cd myBlog
middleman server

Any file wants to be blog needs to be named as or created by following command

middleman article MyNewArticle
middleman article MyNewArticle

Also can add tags in the article

tags: example


tags: [example, tag2]

To list down all articles

<% blog.articles[0...10].each do |article| %>

<% end %>

Project Templates

Go to to download middleman templates

Once select the good one, run command

middleman init -T <template> <folder_name>

For example

middle init -T dtcristo/middleman-cactus cactus

Pretty URLs

Normally, to remove the extension of file in URL, create a folder, move the file in the folder, and rename the file as index.html.erb.

This can be done using configuration in config.rb

activate :directory_indexes

Install Extensions

Download extension from website.

First, update Gemfile, add gem

gem 'middleman-minify-html'

The add configure in config.rb file

activate :minify_html

Then install gem

bundle install

Building Site

Run following command

middleman build

Then the website will be built in build directory.


Middleman - Static Site Generator | Tutorial