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.

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.

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.

On pages without a sidebar on the left, we can place a medium sized image also on the left.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

To use the full width of the main text column is the usual default for stand-alone images.

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

Large

Large images exceed the full text width. The caption is placed in line with the main text at the bottom. Other possible places for the caption would be possible, but aren’t implemented for now.

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 takes up 2 times of the main text width and is oversized on this documentation page. If there is a long table of contents included on a page and a figure with this size and a big height, the TOC may overlap the image in every possible scrolling position.

The size of an extra large image will only show on large desktop screens. Extra-large is an oversize in documentation pages, because it extends beyond the right margin. Therefore, it should be used sparingly and with great care.gm

Layout on documentation pages

The layout some figures is different documentation pages, because we can’t use the left margin there. It’s taken by the sidebar navigation. (See figure documentation page)