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.
- Add the following to your site's
Gemfile
:
gem 'jekyll-image-tag', git: 'https://github.com/sawyerh/jekyll-image-tag'
- Add the following to your site's
_config.yml
:
gems:
- jekyll-image-tag
There are two parts to Jekyll Image 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.
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.
Jekyll Image Tag stores settings in an image
key in your _config.yml.
Example settings
image_tag:
source: assets/images/_fullsize
output: generated
presets:
users:
attr:
class: user-portrait
itemprop: image
width: 350
half:
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.
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.
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 }}" %}.
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.
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.