Published 2020-10-03.
Last modified 2025-05-16.
Time to read: 5 minutes.
jekyll_plugins collection.
This versatile plugin embeds images in HTML documents, with alignment options, flexible resizing, default styling, overridable styling, an optional caption, and an optional URL.
Muliple image formats are supported for each image. The user’s web browser determines the formats which it will accept. The most desirable formats that the web browser supports are prioritized.
For example, if an image is encloded in webp, png and gif filetypes,
and the user’s web browser is relatively recent,
then webp format will give the fastest transmission and look best.
Older browsers, which might not support webp format,
would give best results for png format.
Really old web browsers would only support the gif file type.
Please read the next section for details.
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.
See demo/index.html for examples.
External Images
Images whose src attribute starts with http are assumed to not be served from the Jekyll website.
The jekyll_img plugin generates HTML for external images using an img element with
a src attribute, as you might expect.
Image Fallback
For local files (files served from the Jekyll website),
the jekyll_img plugin generates HTML that falls back to successively
less performant formats.
This is made possible by using a picture element.
For fallback to work, at least 2 versions of every image are required.
For example, an image file might have the following verions:
blah.webp, blah.png and blah.jpg.
Given a tag invocation like {% img src='blah.webp' %},
the plugin would generate a picture element that contains an img sub-element with
the given src attribute,
and a source element for each related image
(blah.png and blah.jpg).
Conceptually, the generated HTML might look something like this:
<picture> <source srcset="blah.png" /> <source srcset="blah.jpg" /> <img src="blah.webp" /> </picture>
If no filetype is given for the image, webp is assumed.
For example, these two invocations yield the same result,
if blah.webp exists on the Jekyll website:
{% img src="blah" %}
{% img src="blah.webp" %}
If both blah.webp and blah.png were available,
the above would fetch and display blah.webp
if the web browser supported webp format,
otherwise it would fetch and display blah.png.
If the browser did not support the picture element,
the img src attribute would be used to specify the image.
Default and Relative Paths
Local images whose path does not start with a slash are assumed to be relative to /assets/images.
Simply specifying the filename of the image will cause it to be fetched from
/assets/images/.
For example, the following all fetch the same image:
{% img src="/assets/images/blah.webp" %}
{% img src="blah.webp" %}
{% img src="blah" %}
To specify an image in a subdirectory of where the page resides,
prepend the relative path with a dot (.).
For example, if the current page resides in a Jekyll collection
with path /collections/,
and an image resides in the /collections/ subdirectory,
the following would result in the same image being displayed:
{% img src="/av_studio/images/blah" %}
{% img src="./images/blah" %}
Lazy Loading
An image can be lazily loaded by providing the lazy keyword.
This feature relies upon the lazy loading capability built into all modern browsers and does not rely upon JavaScript.
While the browser loads an image, it doesn't immediately know the image's dimensions, unless they're explicitly specified. To let the browser reserve enough space on a page for images, and avoid disruptive layout shifts, we recommend adding width and height attributes to all tags.
<img src="image.png"
loading="lazy"
style="height:200px; width:200px;">
This would translate to:
{% img lazy
src="blah.webp"
style="height:200px; width:200px"
%}
You could also specify a class for the img that sets width and height.
The following defines a class called known_size that does this:
.known_size {
width: 50%;
height: 1234px;
}
Use the above class as follows:
{% img lazy
src="blah.webp"
class="known_size rounded shadow"
%}
The image must be fetched in order for HTML
img attributes height='auto' and width='auto' to work.
Thus lazy loading is incompatible with a dimension whose value is specified as auto.
This means that, for lazily loaded images,
height and width must have values that are computable without loading the image.
Because the Jekyll img tag's size attribute only specifies the width attribute,
and sets height to auto, it should not be used with the lazy keyword.
The following examples of implicit and explicit auto dimensions will all give problems:
{% img lazy
caption="A warning will be written to the logger"
size="200px"
src="blah.webp"
%}
{% img lazy
src="blah.webp"
style="height:auto; width:200px"
%}
{% img lazy
src="blah.webp"
style="height:200px; width:auto"
%}
{% img lazy
src="blah.webp"
style="height:200px" {% comment %} width:auto is implied {% endcomment %}
%}
{% img lazy
src="blah.webp"
style="width:200px" {% comment %} height:auto is implied {% endcomment %}
%}
High Priority Loading
An image can be fetched with high priority by providing the priority keyword.
Sample usage:
{% img priority src="blah.webp" %}
The above generates an HTML img tag with a fetchpriority='high' attribute.
If you want to increase the fetch priority of an important image, use fetchpriority='high'.
An image with loading='lazy' and fetchpriority='high'
is still delayed while it's off-screen,
and then fetched with a high priority when it's almost within the viewport.
This combination isn't really necessary because the browser would likely load that image with high priority anyway.
Sample usage combining lazy and high priority loading:
{% img lazy priority
src="blah.webp"
style="height:200px; width:200px"
%}
Supported Filetypes
The following are listed in order of priority. See MDN for more information.
| Filetype | MIME type |
|---|---|
svg
| image/svg+xml
|
avif
| image/avif
|
webp
| image/webp
|
apng
| image/apng
|
png
| image/png
|
jpg, jpeg, jfif, pjpeg, pjp
| image/jpeg
|
gif
| image/gif
|
tif, tiff
| image/tiff
|
bmp
| image/bmp
|
ico, cur
| image/x-icon
|
Because avif is problematic as of 2024-01-08 on Firefox, Chrome and Safari, it is not supported yet.
Installation
Add the following highlighted line to your Jekyll project's Gemfile, within the jekyll_plugins group:
group :jekyll_plugins do
gem 'jekyll_img'
end
And then execute:
$ bundle
Syntax
{% img [Options] src='path' %}
Options are:
-
attribution– Seejekyll_plugin_support. -
align="left|inline|right|center"– Default value isinline. -
alt="Alt text"– Default value is thecaptiontext, if provided. -
caption="A caption"– No default value. -
classes="class1 class2 classN"– Extra<img>classes; default isrounded shadow. -
id="someId"– No default value. -
nofollow– This keyword option Generates `rel='nofollow'`, and is only applicable whenurlis specified. -
size='eighthsize|– Defines width of image.fullsize| halfsize| initial| quartersize| XXXYY| XXX%' initialis the default behavior.eighthsize,fullsize,halfsize,quartersizeare relative to the enclosing tag's width.- CSS units can also be used, for those cases
XXXis a float andYYisunit(see below)
-
style='css goes here'– CSS style for <img>; no default. -
target='none|whatever'– Only applicable whenurlis specified; default value is_blank. -
title="A title"– Default value iscaptiontext, 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`:
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:
{% img src="jekyll_240x103.webp" %}
Additional parameters for each example are shown.
Sizes
Captions
URLs
Classes
Styles
Wrapper Styles
Flow-like
