image
Shortcode
image
shortcode is to facilitate an unified call to facilitate a detailed
image HTML tag instead of the conventional <img>
tag. Also, this shortcode
facilitates multiple outputs rendering like amp.html
and html
outputs.
Example usage:
{{< image "Bissetii Project | Welcome"
"/img/logo/2500x1250-color.png"
"2500"
"1250"
"false"
"lazy"
""
"responsive"
"dark-color"
>}}
This shortcode is available starting from v1.12.0
.
Heads-Up
While the shortcode is useful, it breaks the Markdown syntax conventions due to Hugo specific shortcode feature. Therefore, when using other Markdown renderer, these shortcodes would be rendered as text instead of HTML code fragments.
Also, be careful and stay safe while using this shortcode. It allows any form of HTML to be embedded into your Markdown page.
Using image
image
is a single Bissetii rendering API that renders images on a website.
It uses these tags depending on the output type:
html
-<img>
amp.html
-<amp-img>
Since this is a HTML renderer in Markdown file, you want to call in the
shortcode using the <
symbol instead of %
. The brackets are as follow:
# This is Markdown Heading
Your normal text here.
{{< image "[Title] Title of the Image that serves as alternative text"
"[SourceURL] URL to source image"
"[Width] width of the image to be displayed"
"[Height] height of the image to be displayed"
"[IsMap] isMap boolean to indicate <img> is wrapped by a <a> link"
"[LoadingMode] loading type between eager or lazy"
"[SourceSet] srcset a set of image sources for browser to choose"
"[Layout] layout mode, like responsive, responsive-amp-only, ..."
"[Class] all class tags"
>}}
## Back to Markdown
All parameters are compulsory. The following sub-sections explains each parameters in detail.
Title
Parameter
Title
is used primarily as the value for alt=
attribute. We call it a title
to ensure that you prioritize this attribute before placing an image.
It will be filled in as a string. Example values:
"blue ocean photo"
SourceURL
Parameter
SourceURL
is used primarily as the value for src=
attribute. It loads the
image source from a given URL. Both absolute and relative URLs are acceptable.
It will be filled in as a string. Example values:
"https://www.example.com/img/logo/2500x1250-color.png"
"/img/logo/2500x1250-color.png"
Width
Parameter
Width
is used primarily as the value for width=
attribute. Its loading
depends entirely on Layout
parameter and the output types. In plain HTML,
Width
only loads when Layout
is set to responsive-amp-only
and
responsive-height-only
. However, in AMP HTML, Width
is always loaded.
It will be filled in as a string. Example values:
"2048"
"1024"
You should use the desired rendering width on the page, NOT the actual image width. However, it’s good to ensure the actual width is the same as your value.
Height
Parameter
Height
is used primarily as the value for height=
attribute. Its loading
depends entirely on Layout
parameter and the output types. In plain HTML,
Width
only loads when Layout
is set to responsive-amp-only
and
responsive-width-only
. However, in AMP HTML, Height
is always loaded.
It will be filled in as a string. Example values:
"1152"
"600"
You should use the desired rendering width on the page, NOT the actual image width. However, it’s good to ensure the actual width is the same as your value.
IsMap
Parameter
IsMap
is used primarily as the trigger to include ismap
attribute. This
parameter is only used for plain HTML where the <img>
is a sub-child/wrapped
by a link.
This parameter will be ignored in AMP HTML output.
It is a boolean string. Example values:
"false"
"true"
The recommended value is to set it to "false"
if you are not using it.
LoadingMode
Parameter
LoadingMode
is used primarily as the value for loading=
attribute in <img>
tag. It is meant for informing the browser to load the image immediately or to
lazy-load by view. Visit
here for more
info.
This parameter will be ignored in AMP HTML output.
It is a string. Example values:
"eager"
"lazy"
SourceSet
Parameter
SourceSet
is used primarily as the value for srcset=
attribute in <img>
.
It is meant for browser to select the appropriate image source based on screen
conditions.
This parameter will be ignored in AMP HTML output.
It is a string. Example values:
"www.example.com/img/bg/img_480w.svg 480w,www.example.com/img/bg/img_800w.svg 800w,www.example.com/img/bg/img_1024w.svg 1024w,/img/bg/img_2048w.svg 2048w,/img/bg/img_4096w.svg 4096w"
If you do not want to use it, set it to empty string (""
).
Due to Hugo’s shortcode quote limitation and no line breaks, you need to consolidate all of them before setting this field.
Layout
Parameter
Layout
is used primarily as the value for layout=
attribute in <amp-img>
.
This is a shortcode specific parameter that configures the Width
and Height
parameters to appear in AMP HTML and Plain HTML accordingly.
There are 4 values in string for this parameter:
"responsive" -- ensure both AMP HTML and Plain HTML are responsive.
Width and Height are ignored in Plain HTML.
"responsive-amp-only" -- ensure AMP HTML is responsive. Plain HTML retains
its Width and Height attributes when set.
"responsive-height-only" -- ensure AMP HTML is responsive. Plain HTML retains
its Width attribute when set while Height is
ignored.
"responsive-width-only" -- ensure AMP HTML is responsive. Plain HTML retains
its Height attribute when set while Width is
ignored.
You must always set this to ensure the image is rendered properly.
Class
Parameter
Class
is used primarily as the value for class=
attribute in both <img>
and <amp-img>
tags. It is a full long string.