Skip to content

Commit

Permalink
Move sample templates into sample-templates/ directory; update README
Browse files Browse the repository at this point in the history
  • Loading branch information
@wildlyinaccurate
wildlyinaccurate committed Jul 2, 2018
1 parent d902ec7 commit 3cf3bc7
Show file tree
Hide file tree
Showing 5 changed files with 177 additions and 135 deletions.
236 changes: 101 additions & 135 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,19 +1,23 @@
# jekyll-responsive-image

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/).
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/).

[![Build Status](https://img.shields.io/travis/wildlyinaccurate/jekyll-responsive-image.svg?style=flat-square)](https://travis-ci.org/wildlyinaccurate/jekyll-responsive-image)
[![Coverage Status](https://img.shields.io/coveralls/wildlyinaccurate/jekyll-responsive-image.svg?style=flat-square)](https://coveralls.io/repos/github/wildlyinaccurate/jekyll-responsive-image/badge.svg?branch=master)

## Installation

First, install the gem:
This plugin can be installed in three steps:

### 1. Install the gem

Either add `jekyll-responsive-image` to your Gemfile, or run the following command to install the gem:

```
$ gem install jekyll-responsive-image
```

Then you can either add it to the `gems` section of your `_config.yml`:
Then you can either add `jekyll-responsive-image` to the `gems` section of your `_config.yml`:

```yaml
gems:
Expand All @@ -22,9 +26,100 @@ gems:
Or you can copy the contents of [`responsive_image.rb`](lib/jekyll-responsive-image.rb) into your `_plugins` directory.

## Configuration
### 2. Create an image template file

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.

```twig
{% responsive_image path: assets/my-file.jpg template: _includes/another-template.html %}
```

Any extra attributes will be passed straight to the template as variables.

```twig
{% responsive_image path: assets/image.jpg alt: "Lorem ipsum..." title: "Lorem ipsum..." %}
```

### Liquid variables as attributes

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!

```twig
{% assign path = 'assets/test.png' %}
{% assign alt = 'Lorem ipsum...' %}
{% responsive_image_block %}
path: {{ path }}
alt: {{ alt }}
{% if title %}
title: {{ title }}
{% endif %}
{% endresponsive_image_block %}
```

## Templates

You **must** include a `responsive_image` block in your `_config.yml` for this plugin to work. A full list of the available configuration options is below.
It's easy to build your own custom templates to render images however you want using the template variables provided by jekyll-responsive-image.

### 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<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:

| 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`). |

## All configuration options

A full list of all of the available configuration options is below.

```yaml
responsive_image:
Expand Down Expand Up @@ -94,136 +189,7 @@ responsive_image:
- assets/avatars/*.{jpeg,jpg}
```
## 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.

```twig
{% responsive_image path: assets/my-file.jpg template: _includes/another-template.html %}
```

Any extra attributes will be passed straight to the template as variables.

```twig
{% responsive_image path: assets/image.jpg alt: "Lorem ipsum..." title: "Lorem ipsum..." %}
```

### Liquid variables as attributes

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!

```twig
{% assign path = 'assets/test.png' %}
{% assign alt = 'Lorem ipsum...' %}
{% responsive_image_block %}
path: {{ path }}
alt: {{ alt }}
{% if title %}
title: {{ title }}
{% endif %}
{% endresponsive_image_block %}
```

### Template

You will need to create a template in order to use the `responsive_image` tag. Below are some sample templates to get you started.

#### Responsive images with `srcset`

```twig
{% capture srcset %}
{% for i in resized %}
/{{ i.path }} {{ i.width }}w,
{% endfor %}
{% endcapture %}
<img src="/{{ path }}" alt="{{ alt }}" srcset="{{ srcset | strip_newlines }}">
```

#### Responsive image with `srcset` where the largest resized image is the default

> **Note:** This is useful if you don't want your originals to appear on your site. For example, if you're uploading full-res images directly from a device.

```twig
{% capture srcset %}
{% for i in resized %}
/{{ i.path }} {{ i.width }}w,
{% endfor %}
{% endcapture %}
{% assign largest = resized | sort: 'width' | last %}
<img src="/{{ largest.path }}" alt="{{ alt }}" srcset="{{ srcset | strip_newlines }}">
```

#### Responsive images with `<picture>`

```twig
<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](https://github.com/BBC-News/Imager.js/)

> **Note:** This template assumes an `output_path_format` of `assets/resized/%{width}/%{basename}`

```twig
{% 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>
```

### 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 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

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`). |

### Caching
## Caching
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.
Expand Down
25 changes: 25 additions & 0 deletions sample-templates/imager-js.html
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,25 @@
{% comment %}
Render your responsive images using Imager.js (https://github.com/BBC-News/Imager.js/), with the smallest resized image used as a fallback.

Usage:

{% responsive_image path: assets/image.jpg alt: "A description of the image" %}

(P.S. You can safely delete this comment block)
{% endcomment %}

{% 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>
16 changes: 16 additions & 0 deletions sample-templates/picture.html
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,16 @@
{% comment %}
Render your responsive images using <picture>, with the original asset used as a fallback. Note: If your original assets are not web-friendly (e.g. they are very large), you can use a resized image as the fallback instead. See the srcset-resized-fallback.html template for how to do this.

Usage:

{% responsive_image path: assets/image.jpg alt: "A description of the image" %}

(P.S. You can safely delete this comment block)
{% endcomment %}

<picture>
{% for i in resized %}
<source media="(min-width: {{ i.width }}px)" srcset="/{{ i.path }}">
{% endfor %}
<img src="/{{ path }}">
</picture>
18 changes: 18 additions & 0 deletions sample-templates/srcset-resized-fallback.html
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,18 @@
{% comment %}
Render your responsive images using <img srcset>, with the largest resized image used as a fallback.

Usage:

{% responsive_image path: assets/image.jpg alt: "A description of the image" %}

(P.S. You can safely delete this comment block)
{% endcomment %}

{% assign largest = resized | sort: 'width' | last %}
{% capture srcset %}
{% for i in resized %}
/{{ i.path }} {{ i.width }}w,
{% endfor %}
{% endcapture %}

<img src="/{{ largest.path }}" alt="{{ alt }}" srcset="{{ srcset | strip_newlines }}">
17 changes: 17 additions & 0 deletions sample-templates/srcset.html
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,17 @@
{% comment %}
Render your responsive images using <img srcset>, with the original asset used as a fallback. Note: If your original assets are not web-friendly (e.g. they are very large), you might prefer to use the srcset-resized-fallback.html template.

Usage:

{% responsive_image path: assets/image.jpg alt: "A description of the image" %}

(P.S. You can safely delete this comment block)
{% endcomment %}

{% capture srcset %}
{% for i in resized %}
/{{ i.path }} {{ i.width }}w,
{% endfor %}
{% endcapture %}

<img src="/{{ path }}" alt="{{ alt }}" srcset="{{ srcset | strip_newlines }}">

0 comments on commit 3cf3bc7

Please sign in to comment.