A Middleman based project boilerplate.
JavaScript Ruby CSS Shell
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.



Staging Production
Build Status Build Status


For small-to-mid sized projects - centralize and define:

  • development solutions
  • best practices
  • workflows
  • toolsets


Quick Start

Running Locally

From the command line:

$ git clone git@github.com:RayPatterson/project-boilerplate.git; cd project-boilerplate
$ ./setup.sh

After the gem bundling is complete,
Middleman will begin running a server and display something like:

middleman server -p 8888
== The Middleman is loading
== LiveReload is waiting for a browser to connect
== The Middleman is standing watch at
== Inspect your site configuration at

Open you broswer to http://localhost:8888 or run:

$ rake browser:chrome

The browser should display a small set of modules.


To run the server on a different port: ``` $ rake mm:s[1234] ```

Changing Files

In the interests of segregating the top-level Middleman framework configuration workstream from any related to application development, the source directory is imported from a separate GitHub project.

The default configuration is using the development branch. If you wish to begin your project with another branch run:

$ rake source:change[<branchname>]

Each <branchname> listed expands on the previous one. Current options are:

  1. minimal - Modernizr and Normalize.css, application bootstrapping
  2. single-page - Component architecture, Bourbon and Neat, clowncar image, placeholders
  3. multi-page - Backbone Marionette, Mediaelement.js + YouTube, some carousels

Installing rbenv

If you don't have rbenv, now's the time to get it.

$ brew update; brew install rbenv ruby-build rbenv-gemset

Homebrew will prompt you to add the following to your .bash_profile.

export RBENV_ROOT=/usr/local/var/rbenv
if which rbenv > /dev/null; then eval "$(rbenv init -)"; fi

In order for rbenv commands to be found you will also need to add the line:

export PATH="$PATH:/usr/local/opt/rbenv/shims:/usr/local/opt/rbenv"

$ mkdir /usr/local/var/rbenv/plugins; git clone https://github.com/sstephenson/rbenv-gem-rehash.git /usr/local/var/rbenv/plugins/rbenv-gem-rehash
$ rbenv install 1.9.3-p247

Building Files

This will require installing a few things if you want the Favicon Maker and Image Optim extensions to work.

If you don't have Homebrew, God help you. If you do:

$ brew install imagemagick advancecomp gifsicle jhead jpegoptim jpeg optipng pngcrush

Pngout is still in the stone age at the time of writing, so:

  1. Click here to download the universal Mac binaries.
  2. Unzip and copy the pngout binary to /usr/bin

Now run:

$ rake mm:build:development

A build directory should appear in the project root.

Project Structure

Top Level Folders

source Contains all source files that are processed and compiled by Middleman into the build directory.

data Contains YAML files used to define parameters for Rake tasks and Middleman template data.

lib Contains all Rake tasks. Some can be used for any project, however some have very specific uses and require configuration.

Top Level Files


Not sure what these [dotfiles](http://dotfiles.github.io/) and configs do?
Don't worry, it's safe to leave them in your project.


  • .gitignore - If you find some of your files or folders are not being committed, check this file to see if they are being ignored. Chances are you don't need to version them.
  • .ruby-version - Specifies Ruby version for rbenv (recommended) or RVM (legacy).
  • Gemfile - Used by Bundler to define Ruby gem dependencies. Gemfile.lock is generated from this file and should not be edited directly.
  • config.rb - The Middleman configuration file. Activates and configures Middlman extensions.




This is a configured Middleman project. The project utilizes MM to "build" or "compile" the code base for deployment. Commands have been wrapped in Rake tasks to target development and production build types.


The data folder contains some externalized data that is used by Middleman in config.rb, some of the deployment tasks in lib/tasks and can also be read directly into Middleman templates though the data object.

The Middleman config.rb can also be used to pass the values from data/config.yaml into the application templates. An example of this can be seen in source/assets/js/app.js where the helper <%= build_version %> is used to assigned the build version ID to a JavaScript variable.


In [Sprockets](https://github.com/sstephenson/sprockets), files can be converted to multiple types by multiple processing engines during compiling routine. The order is dictated by the chaining of file extensions. The process for the default Middleman [templating](http://middlemanapp.com/templates/) is explained [here](https://github.com/sstephenson/sprockets#invoking-ruby-with-erb) but in short, if you add the `.erb` extension to any file, you can write Ruby in it access the data object as well as Middleman [Template Helpers](http://middlemanapp.com/helpers/).


There are currently 4 types of builds to support a variety of workstreams and approval processes:

Environment Audience Task
Production User $ rake mm:build:production
Staging Tester $ rake mm:build:staging
Review Stakeholder $ rake mm:build:review
Development Developer $ rake mm:build:development


Activating deployments and their repective targets is configured in: data/project/deployment.yml

Available build targets are:

  1. GitHub Pages
  2. Amazon Web Services

The option to deploy review builds to Heroku with basic auth is forthcoming.

GitHub Pages

By default, the development build is configured to automatically deploy to GitHub Pages.

AWS S3 + CloudFront


Setting up [S3](http://aws.amazon.com/s3/) origin buckets and corresponding [CloudFront](http://aws.amazon.com/cloudfront/) CDN distributions is currently beyond the scope of this documentation.

AWS is configured in: data/project/aws.yml

  region: "us-west-1"                     # S3 bucket region
  bucket: "project-boilerplate-staging"   # S3 bucket name
  subdomain: "d3j8fwmkh3oq8e"             # CloudFront subdomain
  distribution_id: "E36OCSKSYBD2LH"       # CloudFront distribution id

Deployment is configured in: data/project/deployment.yml

  active: false    # Activates deployment process
  target: "aws"    # Defines deploy target

Travis CI


Setting up [Travis CI](https://travis-ci.org/RayPatterson/project-boilerplate/) is currently beyond the scope of this documentation.

Pushing to either the staging or production branches will trigger Travis to perform a build and deploy.

Encypting your AWS keys:

$ travis encrypt S3_ACCESS_KEY_ID=AKQA… --add env.global
$ travis encrypt S3_SECRET_KEY_ID=SHHH… --add env.global

Replace the the secure keys in: .travis.yml

  - secure: m7ET...
  - secure: Nr2R…


When the site debugging flag is `true` the Travis build number will be visible within the console.
E.g. `Build Version --> 99`

Versioning Builds

Versioning is configured in: data/project/deployment.yml

  increment: true   # Increments the build version

The build version ID will be visible in the console.

E.g. Build Version --> v0099

The build can be manually versioned with:

$ rake version:increment

Tagging Builds

Tagging is configured in: data/project/deployment.yml

  tag: true                     # Activates tagging process
  message: "Today is the day"   # Optional Message

The build can be manually tagged with:

$ rake version:tag

Then push with the following:

$ git push --tags


Mobile Detection & Redirect (MDR)

The relationships between desktop/tablet/mobile apps for each environment are set within the data/config.yaml file.


In both the middleware and client-side soltions, Android tablets are treated the same as Android mobile devices.
Client-Side JavaScript Solution

If the redirect needs to rely on JavaScript you may follow these steps:

  1. Open source/assets/js/lib/redirect/redirect.js
  2. Replace "REDIRECT-URL-{DEVICE}" with the appropriate redirect URL's.
  3. Replace "REDIRECT-SEARCH-PATTERN" with the appropriate search patterns.
  4. Optionally replace "REDIRECT-URL-IGNORE" if you want to bypass the redirect on specific URL's.
  5. If you are running on a local port other than "8888" replace as necessary.
  6. Embed this file into the tag of source\index.html.erb.


Once the redirects have been verified, it's recommended for optimial performance that you minify this script and replace the embed of the external file and copy the minified code block into the script tags.
Depricated Rack Middleware Solution

If you are deploying to a hosting service such as Heroku that supports Rack middleware, you may use a middleware based solution.

The current solution in place is https://github.com/talison/rack-mobile-detect

There is some additional configuration that can take place within the Rack config config.ru file.