Published 2020-10-03.
Last modified 2023-08-10.
Time to read: 4 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.
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.
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.
See demo/index.html for examples.
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:
{% 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):
<picture> <source srcset="blah.svg" type="image/svg" /> <source srcset="blah.webp" type="image/webp" /> <source srcset="blah.apng" type="image/apng"> <source srcset="blah.png" type="image/png"> <source srcset="blah.jpg" type="image/jpeg"> <source srcset="blah.jpeg" type="image/jpeg"> <source srcset="blah.jfif" type="image/jpeg"> <source srcset="blah.pjpeg" type="image/jpeg"> <source srcset="blah.pjp" type="image/jpeg"> <source srcset="blah.gif" type="image/gif"> <source srcset="blah.tif" type="image/tiff"> <source srcset="blah.tiff" type="image/tiff"> <source srcset="blah.bmp" type="image/bmp"> <source srcset="blah.ico" type="image/x-icon"> <source srcset="blah.cur" type="image/x-icon"> <img src="blah.png" /> </picture>
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
.
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 thecaption
text, 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 whenurl
is specified. -
size='eighthsize|
– Defines width of image.fullsize| halfsize| initial| quartersize| XXXYY| XXX%' 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 andYY
isunit
(see below)
-
style='css goes here'
– CSS style for <img>; no default. -
target='none|whatever'
– Only applicable whenurl
is specified; default value is_blank
. -
title="A title"
– Default value iscaption
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`
:
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:
{% img src="jekyll_240x103.webp" %}
Additional parameters for each example are shown.