Middleman::Webp

This is Middleman extension that generates WebP versions of each image used in site during build.

WebP is image format developed by Google and it usually generates smaller files than regular jpeg or png formats.

Browser's supporting WebP will include Accepts header to the image file requests so you can refer to jpegs or pngs in your HTML and use for example .htaccess configuration to provide smaller alternatives for browser's supporting WebP.

See my blog post "Introducing WebP extension for Middleman" for more details why I think using WebP matters.

Middleman-webp depends on cwep and gif2webp commandline tools, so install those first for your system.

• Fedora: yum install libwebp-tools
• Ubuntu: apt-get install webp
• OS X: brew install webp --with-giflib
• Or install from the Google's WebP site: https://developers.google.com/speed/webp/download

Add this line to your Middleman site's Gemfile:

gem 'middleman-webp'

And then execute:

$ bundle

And activate :webp extension in your config.rb:

activate :webp

You are not able to use latest gem version if you are using Middleman 3. In that case install gem with following Gemfile statement:

gem 'middleman-webp', '~> 0.3.2'

Support for Rubies <= 2.4 was dropped in 1.0.0 version of this gem. If you are unable to update Ruby version use following Gemfile statement.

gem 'middleman-webp', '< 1.0.0'

Options for conversion are defined using Ruby's glob syntax or Regexp for matching image files and hashes containing args supported by cwebp:

activate :webp do |webp|
  webp.conversion_options = {
    "icons/*.png" => {lossless: true},
    "photos/**/*.jpg" => {q: 100},
    /[0-9]/.+gif$/ => {lossy: true}
  }
end

If there are some image files that you don't want to convert to the webp alternatives, you could ignore them using ignore option matching those paths.

activate :webp do |webp|
  webp.ignore = '**/*.gif'
end

Ignore option accepts one or an array of String globs, Regexps or Procs.

If you want the output images to be named sample.png.webp instead of sample.webp, set the option append_extension to true.

activate :webp do |webp|
  webp.append_extension = true
end

By default Middleman::WebP will only keep .webp versions if they are smaller than original ones.

If you want avoid this behavior and always save .webp version even if they are larger, disable allow_skip option.

activate :webp do |webp|
  webp.allow_skip = false
end

When you use asset_hash extension you may want to change whether WebP image are converted before or after Middleman build, dependin on how you plan to serve/download them.

Default behaviour is to generate WebP images after build, which will create identical filenames with different extension, preserving the original asset_cache hash. This works well if you are going to replace request content based on Accepts header while serving image files by configuring .htaccess or something similar.

However if you are going to determine used file type on client side and want to use asset helpers, it would be good idea to generate WebP versions before build allowing them to have their own asset hashes. In this case you probably want to generate WebP versions always even if they end up to be same size or larger than originals.

activate :webp do |webp|
  webp.run_before_build = true
  webp.allow_skip = false
end

Configure web server to serve WebP images if they are available and browser has set the HTTP Accept header.

Look for this example how to do it in .htaccess.

1. Fork it ( http://github.com/iiska/middleman-webp/fork )
2. Create your feature branch (git checkout -b my-new-feature)
3. Commit your changes (git commit -am 'Add some feature')
4. Push to the branch (git push origin my-new-feature)
5. Create new Pull Request

• Johannes Schleifenbaum
• Ryan Townsend
• François VANTOMME
• Novtopro He
• Joshua Wood