Middleman is powerful, but to get the most out of it you must learn how to configure it. First of all, you should get to know which settings are available to you. Visit http://localhost:4567/__middleman/config to see all settings in your current environment. For each setting it shows a description, current value and default value.

In this post I will share how my config looks like. We already activated LiveReload in the last post, so let us open config.rb again.

Mimic Rails

Being used to the directory structure in Ruby on Rails I wanted to mimic this for my Middleman assets.

set :css_dir, 'assets/stylesheets'
set :images_dir, 'assets/images'
set :js_dir, 'assets/javascripts'

I then created a directory called assets inside source and moved the files there.

GitHub Flavored Markdown (GFM)

Since Kramdown is the default Markdown engine in Middleman and it does not fully support GitHub Flavored Markdown I replaced it with Redcarpet.

Add the following to your Gemfile and then run bundle install:

gem 'redcarpet'

Enable Redcarpet and fenced code blocks in your config.rb:

set :markdown_engine, :redcarpet
set :markdown, fenced_code_blocks: true

Do not forget to activate syntax highlighting:

activate :syntax

The SCSS I am using for syntax highlighting can be found on GitHub.

Build settings

In Middleman you have the option to use different settings for different environments. These are the build settings I am using:

configure :build do
  activate :asset_hash
  activate :asset_host
  activate :gzip
  activate :minify_css
  activate :minify_html
  activate :minify_javascript
  activate :relative_assets
  activate :imageoptim do |options|
    options.manifest = false
    options.svgo = false
  set :asset_host, '//cdn.richardkall.se'

So, what is going on here?

  • With asset_hash my asset filenames will change every time the file content has changed. By doing this, it is possible to cache them for a very long time.
  • I am minifying my CSS, JavaScript and HTML for performance reasons. You need the middleman-minify-html extension to enable HTML minification.
  • My images are optimized using the middleman-imageoptim extension.
  • I am using my own CDN and hosting my assets on CloudFront. I will cover how to set this up in a future post.

If you want to see my entire config.rb you can find it on GitHub.