Enhanced Image Syntax

We can preprocess images (rotate, change ratio, and zoom) and have several options for placing them in and around the text. We can add a caption. All this is achieved by additional parameters associated with the image source.

There are two different ways to place an image in Markdown — stand-alone or embedded. The theme styles them differently by default (→ basic syntax).

CommonMark can handle only 3 parameters inside the image element. To generate a caption and change the layout etc., the theme offers many additional parameters. And there are three ways to associate them with your usual images:

1. Page resource parameters

2. Parameters in a data file

3. Query string parameters attached to the image name

And there are also diagrams generated from code blocks:

4. Parameters as additional code block attributes

How to add parameters to page resources in the frontmatter and how to add global and remote resources in a local data file is described in the introduction to the workflow.

Query string parameters are a specialty for the in-place manipulation of images described below.

Parameters for fenced code blocks are added together with their special attributes (→ code page).

Additional parameters

Many parameters apply to all kinds of images. And there are some especially for normal raster images and some for symbolic images.

General options

Layout

width, posh, posv, caption, attr, attrlink, box, class

We can change the size and the place of an image and add a rich caption:

• The size of an image is determined by the width parameter.

• The horizontal position can be changed with posh. The vertical position parameter posv only adds some space for embedded images in the middle of a text block.

• Besides the caption text, we can also place an attribution with a link in the image caption.

• We can embed an image in a box. The default is a weak small shadow which is nearly invisible for many images.

• In case we want to apply a special styling to an image, we can add a custom CSS class.

Other properties

alt, link, rel

We can add alternative text and a link to the image:

• We can use the alt parameter to add the mandatory alternative description for an image.

  Alternative text in the first square bracket of the image element overrides this resource parameter.

• We can place a link around the image and determine its relation.

Preprocessing for normal raster images

zoom, rotate, ratio, anchor

We can transform images to some extent:

• Zoom and rotate

• A new ratio of an image can be set as the decimal fraction between width and height proportions ––– for example 3:2 = 1.5.

• When we zoom in or change the ratio the image gets usually cropped. The selected area of the image is by default determined by a “smart”. To choose the area manually we can set the anchor to one of the nine available areas.

Options for symbolic images

When we use images with symbolic content (like logos or diagrams) we don’t want to alter them under any circumstances. We especially don’t want to crop them for a preview on navigation cards with a fixed ratio. We also need some options for their background color because many symbolic images include transparent parts and may suffer from a contrast deficit in light or dark mode. And we might want to frame them in a box with some padding or not.

The theme offers a few parameters for their special treatment:

type, background, padding

These parameters change the image layout:

• When we set type to symbol the image is never preprocessed (not even for cards). Every card layout adds some padding and centers the images instead.

• We can choose a background shade to ensure a good contrast. The default is light. Looks only good inside a box.

• We can add some padding around a symbol (inside a box).

Complete overview

The following table shows all image parameters and their possible values in alphabetical order:

Query string parameters

We can use a special syntax to set a 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?width=small&posh=right)

The start of every image 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 use these parameters:

Query-string parameters override frontmatter parameters!