Images

Perplex handles all Markdown images by default as floats inside a text block. Self-contained separate images are the domain of the figure shortcode. But there is a fallback for the widespread self-contained use of Markdown images.

Syntax

Embedding an image is syntactically similar to placing a link. The sole difference: The image element begins with an exclamation mark!.

Short inline notation

![Alternative Text](image.jpg)

The alternative text inside the square brackets [] is used by screen readers, pure text browsers and search engines.

Reference notation

We can use a marker in a second pair of squared brackets to separate the image reference:

![Name][imgref]

We have to provide the image reference somewhere else in the same file by repeating the marker followed by a colon and a space before the path:

[imgref]: long/path/to/image.jpg "Optional Title"

This syntax is especially convenient, when an image is used more than once or when a long path or title would clutter the content.

Passing extra parameters

Markdown can’t handle more image parameters than the ones mentioned above. To offer layout variations, Perplex can handle additional parameters with the help of Hugo. All of them can be given as resource meta-data in the front-matter. Alternatively we can change some layout parameters directly in the Markdown by adding parameters to the image name.

Resource meta-data

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

Parameter	Key	Values
Alternative text	alt	Plain string
Attribution	attr	Inline Markdown string
Attribution link	attrlink	URL
Caption	caption	Inline Markdown string
Class	class	CSS class names
Link	link	URL
Horiz. position	posh	left, right
Vert. position	posv	top, middle
Related	rel	See MDN web docs
Size	size	tiny, small, normal, full
Target	target	_blank, _parent, _self, _top

Adding parameters in-place

We can use a special syntax to set the few layout parameters, which tend to change more often in the process of content creation. The size and the position of an image can be specified like:

![Alternative text](image.jpg?size=small&posh=right)

The start of every name extension is marked by an interrogation mark ?. Then follows a short parameter key, the equal sign = and the parameter value. Consecutive key-value pairs are separated by an ampersand &.¹

We can specify a few parameters to a given set of values:

Parameter	Key	Values
Size	size (s)	tiny, small, normal, full
Horiz. position	posh (ph)	left, right
Vert. position	posv (pv)	top, middle

Overriding resource parameters

When the given parameters are already defined in the resource section of the front-matter, the in-place parameters will override them.

Resolution

Perplex relies on Hugo’s powerful image processing capabilities. Many different sized versions of every image are generated automatically, so every client browser can pick the optimal size to display. We don’t have to worry about all these sizes, but we should supply a large enough original image. For crisp embedded images in the default size, the originals should have a width of at least 990px to allow triple density on screens with high resolution.

In case we can’t provide a large enough version of an image, Perplex uses an excellent interpolation filter provided by Hugo to enlarge its size smoothly. Those interpolated images may look blurry nonetheless, a high resolution of the original is always preferable.

Layout

Perplex embeds every image as a float into the containing text block by default. The default is the most common choice at the beginning of the block. But we may want to place images also in the middle. In both cases following blocks may have to flow around the image, too, when the containing one is short.

At the beginning

This is the most common place for an embedded image. By default its placed on the left, if the screen is wide enough.

Default size

Small size

Tiny size

In the middle

Default

Small

Far, far away, behind the word mountains, far from the countries Vokalia and Consonantia, there live the blind texts. A small embedded imagegm A small river named Duden flows by their place and supplies it with the necessary regelialia.

Tiny

Far far away, behind the word mountains, far from the countries Vokalia and Consonantia, there live the blind texts. Tiny imagegm Far far away, behind the word mountains, far from the countries Vokalia and Consonantia, there live the blind texts.

Fallback to full width

When your content already relies on self-contained Markdown images, it will take some time to restructure them. Because their default layout in Perplex will be broken — the default layout is only half the size of the main text column — we have a fallback.

We can set the configuration parameter embedFull to true in the site configuration to use it for all images. We can also place this parameter in the front-matter of specific pages. Or we can set the size of a specific image to full, which is probably only useful for this demonstration:

![A surreal colored corridor](efe-kurnaz-RnCPiXixooY-unsplash.jpg?size=full)

Efe Kurnaz/ Unsplash

The syntax for query strings has been introduced to extend URLs with optional parameters like https://name.org?id=val&id2=val2. They are usually generated automatically to specify API requests. ↩︎