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:

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

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 &.1

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

ParameterKeyValues
Sizesize (s)tiny, small, normal, full
Horiz. positionposh (ph)left, right
Vert. positionposv (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

The default size for an embedded imagegm 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.

The default size for an embedded imagegm 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

A small embedded imagegm 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.

A small embedded imagegm 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

Tiny imagegm 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.

Tiny imagegm 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

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. The default size for an embedded imagegm 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. The default size for an embedded imagegm 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. A small embedded imagegm 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. A small embedded imagegm 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. Tiny imagegm 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. Separated they live in Bookmarksgrove right at the coast of the Semantics, a large language ocean. Tiny imagegm 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.

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)

A surreal colored corridor Efe Kurnaz/ Unsplash


  1. 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. ↩︎