Setup Middleman

This how-to provides a comprehensive guide to setting up a clean, optimized Middleman project from the ground up. It focuses on best practices for both development and production environments, helping developers maintain a well-organized, performant static site.

Prerequisites

Ruby installed

Target Folder Structure

my_project/
├── source/
│   ├── assets/             ← Assets here
│   │   ├── css/
│   │   ├── img/
│   │   └── js/
│   ├── index.html.slim
│   └── layouts/
│       └── layout.slim
├── .gitignore
├── Gemfile
└── config.rb

Neat Foundation

First of all, we're going to create the foundation for the Sinatra application:

File	Folder	Description
Gemfile	/	App's `gem` dependencies definition

Gemfile creation

Gemfile creation with this command line:

echo "source \"https://rubygems.org\"\n git_source(:github) { |repo| \"https://github.com/#{repo}.git#\" }" > Gemfile

Add Gems

Install the Gems needed to run the application:

bundle add builder middleman middleman-autoprefixer middleman-blog middleman-minify-html nokogiri redcarpet slim terser

Root Files Optimization

`.gitignore` File

Use your terminal:

touch .gitignore

A .gitignore file is created to exclude temporary, OS-specific, and development tool files from version control (e.g., .DS_Store, .idea/, .vscode/, build/). This ensures the Git repository remains clean and focused only on the essential project files, reducing clutter and potential merge conflicts.

.bundle
.cache
.DS_Store
.idea/
.sass-cache
.vscode/
Gemfile.lock
build/

`config.rb` File

Use your terminal:

touch config.rb

This central Middleman configuration file defines how the project behaves during development and build:

Autoprefixer: Automatically adds vendor prefixes to CSS, ensuring compatibility across the latest 2 versions of major browsers.
Layout Settings: Disables layout rendering for certain file types like XML, JSON, and plain text to streamline output.
Asset Paths: Custom directories (assets/css, assets/js, assets/img) are specified for better organization.
Build Optimizations: Enables minification for HTML, CSS, and JavaScript (using Terser) and Gzip compression, significantly reducing file sizes for faster load times in production.

# config.rb

# Activate and configure extensions
# https://middlemanapp.com/advanced/configuration/#configuring-extensions

activate :autoprefixer do |prefix|
  prefix.browsers = "last 2 versions"
end

# Layouts
# https://middlemanapp.com/basics/layouts/

# Per-page layout changes
page '/*.xml', layout: false
page '/*.xsl', layout: false
page '/*.json', layout: false
page '/*.txt', layout: false

# Assets
set :css_dir, 'assets/css'
set :images_dir, 'assets/img'
set :js_dir, 'assets/js'

# Proxy pages
# https://middlemanapp.com/advanced/dynamic-pages/

# proxy(
#   '/this-page-has-no-template.html',
#   '/template-file.html',
#   locals: {
#     which_fake_page: 'Rendering a fake page with a local variable'
#   },
# )

# Helpers
# Methods defined in the helpers block are available in templates
# https://middlemanapp.com/basics/helper-methods/

# helpers do
#   def some_helper
#     'Helping'
#   end
# end

# Build-specific configuration
# https://middlemanapp.com/advanced/configuration/#environment-specific-settings
configure :build do
  # activate: minify_html
  activate :minify_html
  # activate: minify_css
  activate :minify_css
  # activate: minify_javascript, compressor: Terser.new
  activate :minify_javascript, compressor: Terser.new
  # Gzip
  activate :gzip
end

`source` Folders Content Creation

`source/assets` & `source/layouts` Folders

assets/ contains CSS, JavaScript, and images. This structure is designed to scale and supports SCSS preprocessing for cleaner, more powerful styles.

mkdir source
cd source
mkdir assets
mkdir layouts

`source/layouts/layout.slim` File

Use your terminal:

cd layouts
touch layout.slim

layouts/ includes a default Slim-based HTML layout using Middleman's helper tags for automatic CSS and JS linking.

doctype html
html
  head
    meta charset="utf-8"
    meta http-equiv="x-ua-compatible" content="ie=edge"
    meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no"
    title = current_page.data.title || "Middleman"
    = stylesheet_link_tag "site"
    = javascript_include_tag  "site"

  body
    == yield

`source/assets/css/site.css.scss` File

Use your terminal:

cd ../assets/css
mkdir css
touch css/site.css.scss

Copy & paste:

body {
  background-color: #fbc547;
  color: #333;
  font-family: -apple-system, BlinkMacSystemFont, "Avenir Next", "Avenir",
    "Segoe UI", "Lucida Grande", "Helvetica Neue", "Helvetica", "Fira Sans",
    "Roboto", "Noto", "Droid Sans", "Cantarell", "Oxygen", "Ubuntu",
    "Franklin Gothic Medium", "Century Gothic", "Liberation Sans", sans-serif;
  padding: 18vh 1rem;
  text-align: center;
}

a {
  color: rgba(#000, 0.7);

  &:focus,
  &:hover {
    color: rgba(#000, 0.6);
  }
}

.middleman-logo {
  margin-bottom: 1rem;
  width: 10rem;
}

`source/assets/img/.keep` File

.keep file: Added to version control empty directories (like img/) when no assets exist yet — a common convention to ensure directory presence in Git.

cd ../
mkdir img
touch img/.keep

`source/assets/js/site.js` File

Use your terminal:

mkdir js
touch js/site.js

Copy & paste:

// This is where it all goes :)

`source/index.html.slim` File

Use your terminal:

cd ../../
touch index.html.slim

index.html.slim demonstrates a functional landing page with inline SVG and dynamic title rendering from frontmatter, a common Middleman feature.

---
title: Welcome to Middleman
---
svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 400 340" class="middleman-logo" aria-labelledby="middleman-logo__title" role="img"
  title id="middleman-logo__title"
  path class="middleman-logo__top-left-bar" fill-opacity=".45" d="M0 40L200 0v30L0 60z"
  path class="middleman-logo__top-right-bar" fill="#fff" d="M200 0l200 40v20L200 30z"
  path class="middleman-logo__left-m" fill-opacity=".45" d="M0 78v184l45 5V152l45 83 47-83v129l53 7V52l-57 8-43 83-43-70z"
  path class="middleman-logo__right-m" fill="#fff" d="M400 78v184l-45 5V152l-45 83-47-83v129l-53 7V52l57 8 43 83 43-70z"
  path class="middleman-logo__bottom-left-bar" fill-opacity=".45" d="M0 300l200 40v-30L0 280z"
  path class="middleman-logo__bottom-right-bar" fill="#fff" d="M200 340l200-40v-20l-200 30z"

h1 Middleman is Running
= link_to("Read Documentation", "https://middlemanapp.com/basics/templating_language/", target: "_blank")

This setup serves as a lightweight yet robust Middleman boilerplate, ideal for developers who want:

A clean Git history
Pre-configured production optimizations
A scalable project file layout
Easy customization using Slim and SCSS

Perfect for static site generators, documentation portals, or quick prototyping environments.

Build and Deploy

Running one command, bundle exec middleman build, exports the site in a production-ready format. Choose from open source deployment solutions to get your site live.

Setup Middleman

Prerequisites

Target Folder Structure

Neat Foundation

Gemfile creation

Add Gems

Root Files Optimization

.gitignore File

config.rb File

source Folders Content Creation

source/assets & source/layouts Folders

source/layouts/layout.slim File

source/assets/css/site.css.scss File

source/assets/img/.keep File

source/assets/js/site.js File

source/index.html.slim File

Build and Deploy

`.gitignore` File

`config.rb` File

`source` Folders Content Creation

`source/assets` & `source/layouts` Folders

`source/layouts/layout.slim` File

`source/assets/css/site.css.scss` File

`source/assets/img/.keep` File

`source/assets/js/site.js` File

`source/index.html.slim` File