Skip to content


Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?
This branch is 1 commit ahead, 5 commits behind robwierzbowski:master.

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time

Jekyll Image Tag

Better images for Jekyll.

Jekyll Image Tag is a full featured liquid tag for images in the Jekyll static site generator. Store image presets, add classes, alt text, and any other attribute to an image's HTML, and automatically create resized images from a tag argument or a little YAML configuration.

For responsive images in Jekyll, take a look at Jekyll Picture Tag.

This fork contains a small modification for image captions.


Jekyll Image Tag requires Jekyll >=1.0, Minimagick >=3.6, and Imagemagick.

Once you have the requirements installed, copy image_tag.rb into your Jekyll _plugins folder.


There are two parts to Jekyll Image Tag:

Liquid Tag

{% image [preset or WxH] path/to/img.jpg [attr="value"] %}

The tag takes a mix of user input and pointers to configuration settings.


Tells Liquid this is a Jekyll Image Tag.

preset or WxH

Optionally specify a preset or image dimensions. Leave blank to use the image as is.

A preset will resize the image based on the preset's width and height properties, and add any preset attributes to the image's HTML.

Image dimensions follow the format WIDTHxHEIGHT. Each dimension can be either a number of pixels or the keyword AUTO. If one dimension is AUTO the image will scale proportionately. Two numbers will scale and crop.


The base image. Can be a jpeg, png, or gif.


Optionally specify any number of HTML attributes. These will be merged with any attributes you've set in a preset. An attribute set in a tag will override the same attribute set in a preset.

special attribute "title"

As a modification to the original source, the "title" attribute will create a special HTML output if you set it. It will generate a <div class="imgbox"> that is wrapped around the <img> tag and will embed the title as text into the mentioned div. By this, you can place an image caption directly underneath the image.

If you set the "title" attribute to "_alt" it will copy the value from the "alt" attribute.


Jekyll Image Tag stores settings in an image key in your _config.yml.

Example settings

  source: assets/images/_fullsize
  output: generated
        class: user-portrait
        itemprop: image
      width: 350
      width: 400
      height: 400


To make writing tags easier you can specify a source directory for your assets. Base images in the tag will be relative to the source directory.

For example, if source is set to assets/images/_fullsize, the tag {% image stevenson/dream.jpg alt="A night scene" %} will look for a file at assets/images/_fullsize/stevenson/dream.jpg.

Defaults to the site source directory.


Jekyll Image Tag generates resized images to the output directory in your compiled site. The organization of your source directory is maintained in the output directory.

Defaults to {compiled Jekyll site}/generated.

NOTE: output must be in a directory that contains other files or it will be erased. This is a known bug in Jekyll.


Presets contain reusable settings for a Jekyll Image Tag.

For example, a users preset might set image dimensions, a class, and some metadata attributes needed for all user pictures. If the design changes, you can edit the users preset and the new settings will apply to every tag that references it.

A preset name can't contain the ., :, or / characters.


Optionally add a list of html attributes to insert when the preset is used.

Set the value of standalone attributes to nil.

An attribute set in a tag will override the same attribute set in a preset.

width and height

The same as width and height at the tag level, except that dimensions with an AUTO value are omitted. Set a single value to scale the image proportionately. Set both to scale and crop.

Using Liquid variables and JavaScript templating

You can use liquid variables in an image tag:

{% image {{ post.featured_image }} alt="our project" %}

If you're using a JavaScript templating library such as Handlebars.js, the templating expression's opening braces must be escaped with backslashes like \{\{ or \{\%. They'll be output as normal {{ }} expressions in HTML:

{% image {{ post.featured_image }} alt="\{\{ user_name }}" %}.

Managing Generated Images

Jekyll Image Tag creates resized versions of your images when you build the site. It uses a smart caching system to speed up site compilation, and re-uses images as much as possible.

Try to use a base image that is larger than the largest resized image you need. Jekyll Image Tag will warn you if a base image is too small, and won't upscale images.

By using a source directory that is ignored by Jekyll you can prevent huge base images from being copied to the compiled site. For example, source: assets/images/_fullsize and output: generated will result in a compiled site that contains resized images but not the originals.

The output directory is never deleted by Jekyll. You may want to manually clean it every once in a while to remove unused images.

Resizing images is a good first step to improve performance, but you should still use a build process to optimize site assets before deploying. If you're a cool kid, take a look at the Yeoman generator for Jekyll, generator-jekyllrb.


Report bugs and feature proposals in the Github issue tracker. In lieu of a formal styleguide, take care to maintain the existing coding style.

Release History

0.1.2, Aug 4, 2013: Bugfixes.
0.1.1, July 17, 2013: Refactor, add Liquid parsing.
0.1.0, July 14, 2013: Initial release.




Better images for Jekyll.








No packages published


  • Ruby 100.0%