README.md

Middleman 4 + Gulp.js

This is a Middleman template which implements Gulp.js using the new external pipeline feature introduced in Middleman 4.

Features

• Gulp.js - Asset pipeline
• SassC (LibSass) - CSS prepocessor
• Browserify - JavaScript bundling
• Haml - So much cleaner than ERB
• gulp-imagemin - Image minification
• BrowserSync - Fast page reloading when changes are made in development
• Pry - REPL, debugger, overall better console experience
• jQuery and Moment.js - Included as examples and so Browserify has something to bundle. :)
• Web Font Loader - Asynchronous font loading
• Bourbon 5 - Sass mixin library (included via npm)
• Neat 2 - Sass grid system (included via npm)
• Integration and unit testing with Rspec and Capybara
• Linting with ESLint, scss-lint, and haml-lint
• Environment-specific deployment to Amazon S3

Requirements

• Middleman 4.x
• Ruby 2.x
• Node 8.x
• Gulp CLI

Usage

1. Start a new Middleman site using this template.

    $ middleman init my_new_site -T joshukraine/middleman-gulp
   

2. Change into the project root and execute the setup script.

    $ cd my_new_site
    $ chmod +x bin/* # Make sure we can run included scripts
    $ bin/setup
   

3. Start the Middleman server. Note that this will also invoke Gulp via the external pipeline.

    $ bundle exec middleman server
   

4. Initialize a new Git repo.

    $ git init
    $ git add --all
    $ git commit -m "Initial commit"
    $ git remote add origin https://[your-repo-url]
    $ git push -u origin master
   

Deployment

I recommend Amazon S3 for deployment. It's very simple and surprisingly cost effective. Here's how to deploy your site to S3.

1. Read Amazon's guide on Hosting a Static Website

2. In the Gemfile, uncomment and install middleman-s3_sync

3. Configure your deployment configs in environments/production.rb and environments/staging.rb.

4. To deploy, run the deploy script, passing your desired environment as an argument.

    $ bin/deploy production
   
    # OR...
    $ bin/deploy staging
   

BONUS: If you deploy with Amazon, you can get a free ssl certificate for your site!

Environments

Middleman has two default environments: development and production. This template is configured to run the external pipeline (Gulp in our case) in both. There are times, however, when the external pipeline should not run. Two good examples are tests and the console. We therefore define two additional environments: test and console.

Custom environments can be invoked on the command line with -e flag like so:

# Start the console in the console enviroment
$ bundle exec middleman console -e console

Code for custom environments is stored in environments/<your-custom-env>.rb. Note that custom environments can be invoked without the existence of a corresponding file in the environments/ directory. If, for example, you merely wanted to start a server without the default development configs, you could run middleman server -e <anything-here>.

For completeness, all five environments used in this template have corresponding files:

environments/
├── console.rb
├── development.rb
├── production.rb
├── staging.rb
└── test.rb

Middleman vs. Gulp

As I initially experimented with Gulp and Middleman, it was sometimes difficult to determine which tool should handle which tasks. The problem is that, while Gulp and Middleman are very different, they have a fair amount of overlapping functionality. For example, Middleman can minify your CSS and JavaScript right out of the box. So can Gulp. Middleman can also minify your HTML, gzip your files, and automatically reload your browser using LiveReload. And Gulp can do all these things too.

So how do you decide who does what? I think most people would be inclined to have Gulp do it all. That's what it was designed for, and it makes sense to keep all these asset-related tasks in one place. However, since we're using Gulp inside of Middleman - a robust static site generator - I think there are some tasks that are better left to Middleman. Here's how I've broken it down in this template:

Middleman	Gulp
HTML Templating
Minify HTML
Gzip Files
	Preprocess CSS
	Minify CSS
	Minify Javascript
	Sourcemaps
	Autoprefixer
	Bundle JavaScript
	Compress Images
	Copy web fonts
	Browser Reload

Tests

Testing is done with Rspec. A few basic tests are provided as an example. Run your test suite like so:

$ bin/rspec spec/

Aliases

Consider adding the following to your .bashrc or .zshrc file:

mm='bundle exec middleman'
mmb='bundle exec middleman build --clean'
mmc='bundle exec middleman console -e console'
mms='bundle exec middleman server'

Acknowledgements

The following repos were very helpful in setting up this template.

• https://github.com/craigmdennis/middleman-gulp-starter
• https://github.com/thoughtbot/proteus-middleman
• https://github.com/NathanBowers/mm-template
• https://github.com/simonrice/middleman-rspec

Reference

• https://youtu.be/-io8EeB3GHI
• middleman/middleman#1817
• https://forum.middlemanapp.com/t/gulp-and-middleman-4/2012

License

Copyright © 2018 Joshua Steele. MIT License