Learning - Middleman - Static Site Generator

Install

• 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 https://get.rvm.io | 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.

Run

middleman server

Access website via http://localhost:4567

Folders

source
source/images
source/javascripts
source/layouts
source/layouts/layout.erb - default layout
source/stylesheets
source/index.html.erb - default home page
config.rb
Gemfile

Activate LiveReload

LiveReload is able to reload the pages when they changed.

In config.rb file, add following line.

...
page...
...

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/c.html.md.erb.

Front Matter

Front matter can use JSON or YAML

YAML

---
title: Middleman is Running
author: "Mike"
---

JSON

;;;
"title": "New Title"
;;;

Access front matter variable

<%= current_page.data.author %>

Layouts

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', 'http://giraffeacademy.com' %>

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 middlemanapp.com

Layout

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 %>

Partial

• 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>
<br><hr>

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>
<br><hr>

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"
products:
  - Tooth Brush
  - Shampoo
  - Soap

In layout.erb or index.erb file

<%= data.test.dog %>

or

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

If Statement

<% if current_page.data.title == "A" and current_page.data.author %>
  This is the A file
<% elsif current_page.data.title == "B" %>
  This is the B file
<% else %>
  This is not A or B
<% end %>

Sitemap

In layout.erb file

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

or

<% current_resource.parent.data.title %>

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

<% current_resource.children.each do |f| %>
  <% f.data.title %> <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 YYYY-MM-DD-title.md or created by following command

middleman article MyNewArticle
middleman article MyNewArticle

Also can add tags in the article

tags: example

or

tags: [example, tag2]

To list down all articles

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

<% end %>

Project Templates

Go to https://directory.middlemanapp.com/#/templates/all 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 https://directory.middlemanapp.com/#/extensions/all 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.

References

Middleman - Static Site Generator | Tutorial