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 text1 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

AttributeMobileTablet
default (left)
.i-right
.i-midst
.i-small
.i-tiny

Image resolution

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

Placeholder The default size for an embedded image 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 unorthographical 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.

Placeholder The default size for an embedded image 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 unorthographical 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 size

Placeholder A small embedded image 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 unorthographical life.

Placeholder A small embedded image 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 unorthographical life.

Tiny size

Placeholder Tiny image 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.

Placeholder Tiny image 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.

In the middle of a paragraph

Default

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. Placeholder The default size for an embedded image 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 unorthographical 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. The Big Oxmox advised her not to do so, because there were thousands of bad Commas, wild Question Marks and devious Semikoli, but the Little Blind Text didn’t listen.

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. Placeholder The default size for an embedded image 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 unorthographical life.

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.

Far, far away, behind the word mountains, far from the countries Vokalia and Consonantia. Placeholder A small embedded image 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 unorthographical life.

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

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. Placeholder Tiny image 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 unorthographical life.

With a caption

Default

Placeholder The default size for an embedded image 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 unorthographical 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

Placeholder A small embedded image 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 unorthographical 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.

Tiny

Placeholder Tiny image 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 unorthographical 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.

Fallback to full width

Placeholder Efe Kurnaz/ Unsplash


  1. for the alt-attribute. ↩︎