Jekyll Responsive Images is 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:
\n![](\"https://coveralls.io/repos/github/wildlyinaccurate/jekyll-responsive-image/badge.svg?branch=master\"){kind=link}
$ gem install jekyll-responsive_imageThen 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.
\nresponsive_image:\n # [Required]\n # Path to the image template.\n template: _includes/responsive-image.html\n\n # [Optional, Default: 85]\n # Quality to use when resizing images.\n default_quality: 90\n\n # [Optional, Default: []]\n # An array of resize configuration objects. Each object must contain at least\n # a `width` value.\n sizes:\n - width: 480 # [Required] How wide the resized image will be.\n quality: 80 # [Optional] Overrides default_quality for this size.\n - width: 800\n - width: 1400\n quality: 90\n\n # [Optional, Default: assets]\n # The base directory where assets are stored. This is used to determine the\n # `dirname` value in `output_path_format` below.\n base_path: assets\n\n # [Optional, Default: assets/resized/%{filename}-%{width}x%{height}.%{extension}]\n # The template used when generating filenames for resized images. Must be a\n # relative path.\n #\n # Parameters available are:\n # %{dirname} Directory of the file relative to `base_path` (assets/sub/dir/some-file.jpg => sub/dir)\n # %{basename} Basename of the file (assets/some-file.jpg => some-file.jpg)\n # %{filename} Basename without the extension (assets/some-file.jpg => some-file)\n # %{extension} Extension of the file (assets/some-file.jpg => jpg)\n # %{width} Width of the resized image\n # %{height} Height of the resized image\n #\n output_path_format: assets/resized/%{width}/%{basename}\n\n # By default, only images referenced by the responsive_image and responsive_image_block\n # tags are resized. Here you can set a list of paths or path globs to resize other\n # images. This is useful for resizing images which will be referenced from stylesheets.\n extra_images:\n - assets/foo/bar.png\n - assets/bgs/*.png\n - 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.
\n{% 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.
\n\nImportant! The attributes in the
\nresponsive_image_blocktag are parsed as YAML, so whitespace and indentation are significant!
{% assign path = 'assets/test.png' %}\n{% assign alt = 'Lorem ipsum...' %}\n\n{% responsive_image_block %}\n path: {{ path }}\n alt: {{ alt }}\n {% if title %}\n title: {{ title }}\n {% endif %}\n{% 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.
srcset{% capture srcset %}\n {% for i in resized %}\n /{{ i.path }} {{ i.width }}w,\n {% endfor %}\n{% endcapture %}\n\n<img src="/{{ path }}" alt="{{ alt }}" srcset="{{ srcset | strip_newlines }} /{{ original.path }} {{ original.width }}w">
<picture><picture>\n {% for i in resized %}\n <source media="(min-width: {{ i.width }}px)" srcset="/{{ i.path }}">\n {% endfor %}\n <img src="/{{ path }}">\n</picture>
\n\nNote: This template assumes an
\noutput_path_formatofassets/resized/%{width}/%{basename}
{% assign smallest = resized | sort: 'width' | first %}\n\n<div class="responsive-image">\n <img class="responsive-image__placeholder" src="/{{ smallest.path }}">\n <div class="responsive-image__delayed" data-src="/assets/resized/{width}/{{ original.basename }}"></div>\n</div>\n\n<script>\n new Imager('.responsive-image__delayed', {\n availableWidths: [{{ resized | map: 'width' | join: ', ' }}]\n onImagesReplaced: function() {\n $('.responsive-image__placeholder').hide();\n }\n });\n</script>
The following variables are available in the template:
\n| Variable | \nType | \nDescription | \n
|---|---|---|
path | \nString | \nThe path of the unmodified image. This is always the same as the path attribute passed to the tag. | \n
resized | \nArray | \nAn array of all the resized images. Each image is an Image Object. | \n
original | \nObject | \nAn Image Object containing information about the original image. | \n
* | \nString | \nAny other attributes will be passed to the template verbatim as strings. | \n
Image objects (like original and each object in resized) contain the following properties:
| Variable | \nType | \nDescription | \n
|---|---|---|
path | \nString | \nThe path to the image. | \n
width | \nInteger | \nThe width of the image. | \n
height | \nInteger | \nThe height of the image. | \n
basename | \nString | \nBasename of the file (assets/some-file.jpg => some-file.jpg). | \n
dirname | \nString | \nDirectory of the file relative to base_path (assets/sub/dir/some-file.jpg => sub/dir). | \n
filename | \nString | \nBasename without the extension (assets/some-file.jpg => some-file). | \n
extension | \nString | \nExtension of the file (assets/some-file.jpg => jpg). | \n