Image
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
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.
Cozy lummox gives smart squid who asks for job pen. Brick quiz whangs jumpy veldt fox. Public junk dwarves quiz mighty fox.