A Jekyll plugin and utility for automatically resizing images. Its intended use is for sites which want to display responsive images using something like srcset
or Imager.js.
First, install the gem:
$ gem install jekyll-responsive-image
Then you can either add it to the gems
section of your _config.yml
:
gems:
- jekyll-responsive-image
Or you can copy the contents of responsive_image.rb
into your _plugins
directory.
An example configuration is below.
responsive_image:
# [Required]
# Path to the image template.
template: _includes/responsive-image.html
# [Optional, Default: 85]
# Quality to use when resizing images.
default_quality: 90
# [Optional, Default: []]
# An array of resize configuration objects. Each object must contain at least
# a `width` value.
sizes:
- width: 480 # [Required] How wide the resized image will be.
quality: 80 # [Optional] Overrides default_quality for this size.
- width: 800
- width: 1400
quality: 90
# [Optional, Default: assets]
# The base directory where assets are stored. This is used to determine the
# `dirname` value in `output_path_format` below.
base_path: assets
# [Optional, Default: assets/resized/%{filename}-%{width}x%{height}.%{extension}]
# The template used when generating filenames for resized images. Must be a
# relative path.
#
# Parameters available are:
# %{dirname} Directory of the file relative to `base_path` (assets/sub/dir/some-file.jpg => sub/dir)
# %{basename} Basename of the file (assets/some-file.jpg => some-file.jpg)
# %{filename} Basename without the extension (assets/some-file.jpg => some-file)
# %{extension} Extension of the file (assets/some-file.jpg => jpg)
# %{width} Width of the resized image
# %{height} Height of the resized image
#
output_path_format: assets/resized/%{width}/%{basename}
# [Optional, Default: []]
# By default, only images referenced by the responsive_image and responsive_image_block
# tags are resized. Here you can set a list of paths or path globs to resize other
# images. This is useful for resizing images which will be referenced from stylesheets.
extra_images:
- assets/foo/bar.png
- assets/bgs/*.png
- assets/avatars/*.{jpeg,jpg}
Replace your images with the responsive_image
tag, specifying the path to the image in the path
attribute.
{% responsive_image path: assets/my-file.jpg %}
You can override the template on a per-image basis by specifying the template
attribute.
{% responsive_image path: assets/my-file.jpg template: _includes/another-template.html %}
Any extra attributes will be passed straight to the template as variables.
{% responsive_image path: assets/image.jpg alt: "Lorem ipsum..." title: "Lorem ipsum..." %}
You can use Liquid variables as attributes with the responsive_image_block
tag. This tag works in exactly the same way as the responsive_image
tag, but is implemented as a block tag to allow for more complex logic.
Important! The attributes in the
responsive_image_block
tag are parsed as YAML, so whitespace and indentation are significant!
{% assign path = 'assets/test.png' %}
{% assign alt = 'Lorem ipsum...' %}
{% responsive_image_block %}
path: {{ path }}
alt: {{ alt }}
{% if title %}
title: {{ title }}
{% endif %}
{% endresponsive_image_block %}
You will need to create a template in order to use the responsive_image
tag. Below are some sample templates to get you started.
{% capture srcset %}
{% for i in resized %}
/{{ i.path }} {{ i.width }}w,
{% endfor %}
{% endcapture %}
<img src="/{{ path }}" alt="{{ alt }}" srcset="{{ srcset | strip_newlines }} /{{ original.path }} {{ original.width }}w">
<picture>
{% for i in resized %}
<source media="(min-width: {{ i.width }}px)" srcset="/{{ i.path }}">
{% endfor %}
<img src="/{{ path }}">
</picture>
Responsive images using Imager.js
Note: This template assumes an
output_path_format
ofassets/resized/%{width}/%{basename}
{% assign smallest = resized | sort: 'width' | first %}
<div class="responsive-image">
<img class="responsive-image__placeholder" src="/{{ smallest.path }}">
<div class="responsive-image__delayed" data-src="/assets/resized/{width}/{{ original.basename }}"></div>
</div>
<script>
new Imager('.responsive-image__delayed', {
availableWidths: [{{ resized | map: 'width' | join: ', ' }}]
onImagesReplaced: function() {
$('.responsive-image__placeholder').hide();
}
});
</script>
The following variables are available in the template:
Variable | Type | Description |
---|---|---|
path |
String | The path of the unmodified image. This is always the same as the path attribute passed to the tag. |
resized |
Array | An array of all the resized images. Each image is an Image Object. |
original |
Object | An Image Object containing information about the original image. |
* |
String | Any other attributes will be passed to the template verbatim as strings. |
Image objects (like original
and each object in resized
) contain the following properties:
Variable | Type | Description |
---|---|---|
path |
String | The path to the image. |
width |
Integer | The width of the image. |
height |
Integer | The height of the image. |
basename |
String | Basename of the file (assets/some-file.jpg => some-file.jpg ). |
dirname |
String | Directory of the file relative to base_path (assets/sub/dir/some-file.jpg => sub/dir ). |
filename |
String | Basename without the extension (assets/some-file.jpg => some-file ). |
extension |
String | Extension of the file (assets/some-file.jpg => jpg ). |