The CommonMark image syntax is simple and the theme additionally distinguishes between two possible image positions: stand-alone & embedded.

Syntax

The CommonMark image element is syntactically very similar to a link. The only difference is, that the image element begins with an exclamation mark: !.

There are also two notations to reference the source: Directly inline or with an additional reference.

Notation

Inline

![Alternative Text](image.jpg "Optional Title")

The alternative text inside the square brackets [] is used by screen readers, pure text browsers, and all kinds of data scrapers.

The optional title becomes the title attribute in the <img> tag.

Reference

We can place 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"

Placement

CommonMark doesn’t care, where we place an image element. But since version 0.108.0 Hugo does! The two distinctive ways lead to a different layout:

Stand-alone

Paragraph before…

![Name][imgref]

Paragraph after…

By surrounding an image element with empty lines it becomes a Markdown block element and gets treated as a figure.

Embedded

![Name][imgref] The paragraph 
containing the image

When we place an image inside our paragraph text–usually at the beginning–it’s embedded as a float.

Layout

Stand-alone

The default for the usual stand-alone CommonnMark image element is the normal size and occupies the main text width as usual in most web layouts.

Placeholder image

Cozy lummox gives smart squid who asks for job pen. Brick quiz whangs jumpy veldt fox. Public junk dwarves quiz mighty fox.

Embedded