Published 2020-10-03.
Last modified 2023-05-18.
Time to read: 3 minutes.
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.
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: continue_on_error: true
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.
