A [Jekyll](http://jekyllrb.com/) plugin for automatically resizing images. Fully configurable and unopinionated, jekyll-responsive-image allows you to display responsive images however you like: using [`<img srcset>`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/Img#attr-srcset), [`<picture>`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/picture), or [Imager.js](https://github.com/BBC-News/Imager.js/).
You will need to create a template in order to use the `responsive_image` and `responsive_image_block` tags. Normally the template lives in your `_includes/` directory. Not sure where to start? [Take a look at the sample templates](sample-templates).
For more advanced templates, see the [**Templates**](#templates) section below.
### 3. Configure the plugin
You **must** have a `responsive_image` block in your `_config.yml` for this plugin to work. The minimum required configuration is a `template` path:
```yaml
responsive_image:
template: _includes/responsive-image.html
```
For a list of all the available configuration options, see the [**All configuration options**](#all-configuration-options) section below.
## Usage
Replace your images with the `responsive_image` tag, specifying the path to the image in the `path` attribute.
```twig
{% responsive_image path: assets/my-file.jpg %}
```
You can override the template on a per-image basis by specifying the `template` attribute.
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!
| `path` | String | The path of the unmodified image. This is always the same as the `path` attribute passed to the tag. |
| `resized` | Array<Object> | 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 (see below). |
Any other attributes that are given to the `responsive_image` or `responsive_image_block` tags will be available in the template. For example the following tag will provide an `{{ alt }}` variable to the template:
```twig
{% responsive_image path: assets/my-file.jpg alt: "A description of the image" %}
```
#### Image Objects
Image objects (like `original` and each object in `resized`) contain the following properties:
You may be able to speed up the build of large sites by enabling render caching. This is usually only effective when the same image is used many times, for example a header image that is rendered in every post.
The recommended way to enable caching is on an image-by-image basis, by adding `cache: true` to the tag:
If you'd like your changes to be considered for the original repository, simply submit a pull request after you've made your changes. Please make sure all tests pass.