Because no Markdown element corresponds to the complex HTML <figure> tag, we need this shortcode for self-contained stand-alone images.

Hugo already provides a figure shortcode and Perplex overrides this shortcode.

Syntax

The original syntax remains valid with two exceptions.

  1. The Perplex shortcode allows to write the caption between the starting and closing shortcode tag. When there is no shortcode closing tag, we need to add a slash to the last angled bracket, to mark the shortcode as self-closing like {{< figure src="image" />}}.

    Should we miss the self-closing slash, Hugo can’t recognize the mistake and expects a closing tag. It will treat all the following Markdown as the caption and produce a probably very garbled page.

  2. The title parameter has a different meaning in Perplex. The Hugo shortcode treats it as a title for the caption and generates a <h4> tag. The Perplex figure instead uses the title parameter as title attribute and adds it to the resulting figure tag, because captions should contain only inline Markdown in the Perplex layout.

The Perplex version offers the same set of named parameters as Hugo’s built-in shortcode and a few more to specify size and position of a figure.

Named parameters

We can specify the following parameters with the given key names and types of values:

ParameterKeyValues
Alternative textaltPlain string
AttributionattrInline Markdown string
Attribution linkattrlinkURL
CaptioncaptionInline Markdown string
ClassclassCSS class names
LinklinkURL
Horiz. positionposhleft, right
Vert. positionposvtop, middle
RelatedrelSee MDN web docs
Sizesizetiny, small, normal, full
Targettarget_blank, _parent, _self, _top

When we need many of these parameters, the figure tag gets very long and therefore prone to typing errors. Perplex also offers the alternative to specify these parameters in the resources section of the front-matter.

Overriding of front-matter meta-data

When we have set parameters in the front-matter and also specify them in named parameters for the shortcode, the latter will override the former. Same goes for the optional caption between the shortcode tags.

Layout

The numbers in the following placeholder images are roughly a multiple of the main text width.

Small

Small portrait figure on the rightgm

Far far away, behind the word mountains, far from the countries Vokalia and Consonantia, there live the blind texts. Separated they live in Bookmarksgrove right at the coast of the Semantics, a large language ocean. A small river named Duden flows by their place and supplies it with the necessary regelialia.

It is a paradisematic country, in which roasted parts of sentences fly into your mouth. Even the all-powerful Pointing has no control about the blind texts it is an almost unorthographic life. One day however a small line of blind text by the name of Lorem Ipsum decided to leave for the far World of Grammar.

Small figure on the left (default horizontal position)gm

Far far away, behind the word mountains, far from the countries Vokalia and Consonantia, there live the blind texts. Separated they live in Bookmarksgrove right at the coast of the Semantics, a large language ocean. A small river named Duden flows by their place and supplies it with the necessary regelialia.

Medium

This size is a good choice for images with a landscape ratio. On smaller screens with only two columns its displayed like a small image.gm

Far far away, behind the word mountains, far from the countries Vokalia and Consonantia, there live the blind texts. Separated they live in Bookmarksgrove right at the coast of the Semantics, a large language ocean. A small river named Duden flows by their place and supplies it with the necessary regelialia.

It is a paradisematic country, in which roasted parts of sentences fly into your mouth. Even the all-powerful Pointing has no control about the blind texts it is an almost unorthographic life. One day however a small line of blind text by the name of Lorem Ipsum decided to leave for the far World of Grammar.

Normal

The default normal size is using the full text width. If the margin is available, the caption is placed there.gm

Large

In the documentation layout the large size fills the text width and the right margin. The text of the caption is constrained to the text width. The attribution is placed in the right margin an on the right as usual.gm

Extra Large

This size could take up 2 times of the main text width but is oversized on this documentation page. If there is a long table of contents included on a page and a figure with this size, the TOC may overlap the image in every possible scrolling position. Therefore, this size doesn’t get bigger than large figures on documentation pages.

The size of an extra large image will only show in blog and article pages. Extra-large would be oversized on a documentation page, because the sidebar navigation blocks the left margin.gm

Layout on blog and article pages

The layout of some figures is different on blog and article pages, because we can also use the left margin there. (see figure posting)