Images

With Perplex, Markdown images should always be embedded in a text block. Self-contained images are the domain of the figure shortcode.

Syntax

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

Short inline notation

![Name](image.jpg)

The name of the image element inside the square brackets [] is used as alternative text¹ in case the browser can’t display the image and is mandatory.

This syntax is preferable when the relative path name is short — like for images in a Hugo page bundle.

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.

Block Attributes

Attribute	Mobile	Tablet
default (left)
.i-right
.i-midst
.i-small
.i-tiny

Perplex relies on Hugo’s image processing capabilities to generate differently sized versions of every image. Thereby, every browser can pick the smallest sufficient size based on the actual width of the image and the pixel density of the actual screen.

For good results, the original images should have a width of at least 660px to allow double density on screens with a high resolution.

Layout

First, copies with different sizes are generated for the given image. They are all placed with the srcset-attribute inside the <img>-tag and to be at the disposal of the browsers. Based on the actual size of the image and the device resolution, every browser can download the optimal version.^*

Perplex embeds every image as a float into the containing paragraph. The most obvious place is at the beginning of paragraph. But we may want to place images also in the middle of a paragraph. In both cases following paragraphs may flow around the image, too, when the containing paragraph is not very long.

Because the image element is so easy to use, authors often include images self-contained between paragraphs. This is a problematic practice, because the image element will always be wrapped inside a paragraph in the resulting HTML.^** Therefore, the standard floating layout in Perplex will be broken.

The best way

to deal with self-contained images in Perplex is to use the figure-shortcode, that includes the image.

At the beginning of a paragraph

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

Default size

Small size

Tiny size

In the middle of a paragraph

Default

Small

Far, far away, behind the word mountains, far from the countries Vokalia and Consonantia, there live the blind texts. Placeholder A small embedded image 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. Far far away, behind the word mountains, far from the countries Vokalia and Consonantia, there live the blind texts. Placeholder Tiny image

for the alt-attribute. ↩︎

Images

Syntax

Short inline notation

Reference notation

Block Attributes

Image resolution

Layout

The best way

At the beginning of a paragraph

Default size

Small size

Tiny size

In the middle of a paragraph

Default

Small

Tiny

With a caption

Default

Small

Tiny

Fallback to full width