Mike Slinn
Mike Slinn

jekyll_img

Published 2020-10-03. Last modified 2023-08-10.
Time to read: 3 minutes.

This page is part of the jekyll_plugins collection, categorized under Jekyll.

This versatile plugin embeds images in HTML documents, with alignment options, flexible resizing, default styling, overridable styling, an optional caption, and an optional URL.

I explain why the webp image format is important in Converting All Images in a Website to webp Format. That article also provides 2 bash scripts for converting existing images to and from webp format.

If you are not using webp images in your Jekyll website, this plugin is not for you. Please read the next section for details.

If you have a use case that would benefit from expanding the supported file types, please describe your use case on the issue tracker.

Image Fallback

This plugin provides support for the webp image format, with a fallback to png format by using the HTML picture element.

This means that 2 versions of every image are required: a webp version, and a png version.

You specify the desired image with a .webp filetype (or no filetype), and the plugin generates a picture element that contains a primary source sub-element that specifies the given image URL, and a secondary img sub-element with a png filetype.

For example, these two invocations yield the same result:

Shell
{% img src="blah" %}
{% img src="blah.webp" %}

The above conceptually generates the following (to support the other options, the generated HTML can be a lot more complex):

Shell
<picture>
  <source srcset="blah.webp" type="image/webp" />
  <source srcset="blah.png" type="image/png" />
  <img src="blah.png"  />
</picture>

The above would fetch and display blah.webp if the web browser supported webp format, otherwise it would fetch and display blah.png.

Installation

Add the following highlighted line to your Jekyll project's Gemfile, within the jekyll_plugins group:

Shell
group :jekyll_plugins do
  gem 'jekyll_img'
end

And then execute:

Shell
$ bundle

Syntax

Shell
{% img [Options] src='path' %}

Options are:

  • attribution – See jekyll_plugin_support.
  • align="left|inline|right|center" – Default value is inline.
  • alt="Alt text" – Default value is the caption text, if provided.
  • caption="A caption" – No default value.
  • classes="class1 class2 classN" – Extra <img> classes; default is rounded shadow.
  • id="someId" – No default value.
  • nofollow – This keyword option Generates `rel='nofollow'`, and is only applicable when url is specified.
  • size='eighthsize|fullsize|halfsize|initial|quartersize|XXXYY|XXX%' – Defines width of image.
    • initial is the default behavior.
    • eighthsize, fullsize, halfsize, quartersize are relative to the enclosing tag's width.
    • CSS units can also be used, for those cases XXX is a float and YY is unit (see below)
  • style='css goes here' – CSS style for <img>; no default.
  • target='none|whatever' – Only applicable when url is specified; default value is _blank.
  • title="A title" – Default value is caption text, if provided.
  • url='https://domain.com' – No default value.
  • wrapper_class='class1 class2 classN' – Extra CSS classes for wrapper <div>; no default value.
  • wrapper_style='background-color: black;' – CSS style for wrapper <div>; no default value.

unit is one of: Q, ch, cm, em, dvh, dvw, ex, in, lh, lvh, lvw, mm, pc, px, pt, rem, rlh, svh, svw, vb, vh, vi, vmax, vmin, or vw.

CSS classes referenced by the jekyll_img plugin are at the bottom of the demo stylesheet. CSS marker classes are included, so CSS selectors can be used for additional styling.

Configuration

By default, any errors cause Jekyll to abort. You can allow Jekyll to continue by setting the following in _config.yml`:

Shell
jekyll_img:
  die_on_img_error: false

Wrapper Div

To make the plugin code more manageable, the plugin always encloses the generated HTML & CSS within a wrapper <div />. The wrapper allows for a simple, consistent approach regardless of whether a caption is generated or not.

The wrapper width is identical to the displayed image width. Within the wrapper <div />, the embedded <img /> is displayed with width=100%. If a caption is required, the generated <figure /> only makes the space taken by the generated HTML longer; the image’s width and height are not affected.

The wrapper will not exceed the width of the tag that encloses it if the size parameter has values eighthsize, fullsize, halfsize, initial or quartersize.

The wrapper’s width can be defined independently of its enclosing tag by using CSS units for the size parameter: Q, ch, cm, em, dvh, dvw, ex, in, lh, lvh, lvw, mm, pc, px, pt, rem, rlh, svh, svw, vb, vh, vi, vmax, vmin, or vw. Using CSS units means that large enough values could cause the image to exceed the width of its enclosing tag.

Usage Examples

All of these examples have a src parameter, like this:

Shell
{% img src="jekyll_240x103.webp" %}

Additional parameters for each example are shown.

Sizes

No other parameters specified
size='initial'
size='fullsize'
size='halfsize'
size='quartersize'
size='eighthsize'
size='15em'
size='10%'
align='left' size='quartersize'
align='center' size='quartersize'
align='right' size='quartersize'
align='right' size='eighthsize'
align='right' size='15em'
align='right' size='10%'

Captions

caption='...'
This is a long, long, long, long, long, long caption
This is a long, long, long, long, long, long caption
align='left' caption='...'
This is a long, long, long, long, long, long caption
This is a long, long, long, long, long, long caption
align='center' caption='...'
This is a long, long, long, long, long, long caption
This is a long, long, long, long, long, long caption
align='right' caption='...'
This is a long, long, long, long, long, long caption
This is a long, long, long, long, long, long caption
align='right' caption='...' size='quartersize'
This is a long, long, long, long, long, long caption
This is a long, long, long, long, long, long caption
align='left' caption='...' size='20%'
This is a long, long, long, long, long, long caption
This is a long, long, long, long, long, long caption
align='center' caption='...' size='20%'
This is a long, long, long, long, long, long caption
This is a long, long, long, long, long, long caption
align='right' caption='...' size='20%'
This is a long, long, long, long, long, long caption
This is a long, long, long, long, long, long caption

URLs

url='https://www.mslinn.com'
caption='This is a caption' url='https://mslinn.com'

Classes

class='rounded bg_yellow shadow' url='https://mslinn.com'
size='150px' url='https://mslinn.com' wrapper_class='bg_yellow'

Styles

class='bg_yellow rounded' style='padding: 1em;'
align='center' class='bg_yellow rounded' style='padding: 1em;'
align='right' class='' nofollow style='padding: 1em;'

Wrapper Styles

align & wrapper_style
align, caption & wrapper_style
This is a caption
This is a caption
This is a caption
This is a caption

Flow-like