middleman-imgix Build Status Gem Version

middleman-imgix is an extension for the Middleman static site generator that allows you to run all of your images (or only some) through imgix for all sorts of fun features.


From inside the Gemfile of your Middleman project | add:

gem 'middleman-imgix'

Then run bundle install


Activate the extension in your config.rb file, and supply your required imgix host:

activate :imgix, host: 'your-subdomain.imgix.net'

A number of other options are supported as well (see the imgix gem for more info):

activate :imgix, host: 'your-subdomain.imgix.net', secure_url_token: 'your-token', shard_strategy: :cycle

Here's a list of all available options:

Option Default Description
host (required) nil A string or array of your imgix hosts.
secure_url_token nil Your imgix secure_url_token.
use_https true Whether to use http or https for imgix.
shard_strategy :crc Your imgix shard strategy.
include_library_param true Include the imgix library param in each URL.
default_params { auto: 'format' } Default imgix params to use on all images.
imgix_js_version nil Converts image_tags to support imgix.js version 2 or 3.
exts %w(.png .jpg .jpeg) List of file extensions that get converted to imgix URLs.
sources %w(.css .htm .html .js .php .xhtml) List of source extensions that are searched for imgix images.
ignore [] Regexes of filenames to skip adding imgix to.
rewrite_ignore [] Regexes of filenames to skip processing for path rewrites.


After activating the extension, all applicable image URLs throughout your site (HTML, CSS, etc.) will begin pointing to imgix. For example...

image_tag 'example.png'
#=> <img src="https://your-subdomain.imgix.net/images/example.png?ixlib=rb-1.1.0&auto=format" />


If you're using imgix.js for responsive images (you still need to include that JS file yourself), you can configure the imgix_js_version option to have the output from image_tag generate specific markup for your imgix.js version.

imgix_js_version: 3

image_tag 'example.png'
#=> <img ix-src="https://your-subdomain.imgix.net/images/example.png?ixlib=rb-1.1.0&auto=format" />

imgix_js_version: 2

image_tag 'example.png'
#=> <img data-src="https://your-subdomain.imgix.net/images/example.png?ixlib=rb-1.1.0&auto=format" class="imgix-fluid" />