jekyll-responsive-image/README.md

# Jekyll Responsive Images

Jekyll Responsive Images is a [Jekyll](http://jekyllrb.com/) plugin and utility for automatically resizing images. Its intended use is for sites which want to display responsive images using something like [`srcset`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/Img#Specifications) or [Imager.js](https://github.com/BBC-News/Imager.js/).

[![Build Status](https://travis-ci.org/wildlyinaccurate/jekyll-responsive-images.svg?branch=master)](https://travis-ci.org/wildlyinaccurate/jekyll-responsive-images)
[![Coverage Status](https://img.shields.io/coveralls/wildlyinaccurate/jekyll-responsive-images.svg)](https://coveralls.io/r/wildlyinaccurate/jekyll-responsive-images)
[![Dependency Status](https://gemnasium.com/wildlyinaccurate/jekyll-responsive-images.svg)](https://gemnasium.com/wildlyinaccurate/jekyll-responsive-images)

## Installation

You can either use the gem and update your `_config.yml`:

```
$ gem install jekyll-responsive_image
```

```yaml
# _config.yml
gems: [jekyll-responsive_image]
```

Or you can simply copy [`responsive_image.rb`](lib/jekyll/responsive_image.rb) into your `_plugins` directory.

## Configuration

An example configuration is below.

```yaml
responsive_image:
  template: '_includes/responsive-image.html' # Path to the template to render. Required.

  # An array of resize configurations. When this array is empty (or not specified),
  # no resizing will take place.
  sizes:
    - width: 480 # How wide the resized image will be. Required
    - width: 800
      quality: 90 # Override JPEG quality (default is 85). Optional.
    - width: 1400
```

## Usage

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..." %}
```

### Template

You will need to create a template in order to use the `responsive_image` tag. A sample template is below.

```html
<img src="/{{ path }}"
     alt="{{ alt }}"
     title="{{ title }}"

     {% if resized %}
         srcset="{% for i in resized %}
             /{{ i.path }} {{ i.width }}w{% if forloop.last == false %},{% endif %}
         {% endfor %}"
     {% endif %}
>
```

#### Template Variables

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 contains the properties listed below.                 |
| `*`       | String | Any other attributes will be passed to the template verbatim as strings.                             |

Each element in the `resized` array contains the following properties:

| Variable | Type     | Description                      |
|----------|----------|----------------------------------|
| `path`   | String   | The path of the resized image.   |
| `width`  | Integer  | The width of the resized image.  |
| `height` | Integer  | The height of the resized image. |