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

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:

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:
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
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.
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
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.
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
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.
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.
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.
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 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.
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.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.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:

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