Annotation syntax

Every parameter lives in the image alt text, separated by |. Fields starting with ag: are parameters; the first field that does not start with ag: is the caption.

Syntax rules

![caption|ag:layout=float|ag:side=right|ag:width=38%](assets/photo/11-shore.jpg)

Rule	Explanation
Separator	the pipe |, nothing else
Prefix	parameters must start with ag:, the key follows the colon
Assignment	use =, not a colon
Caption position	the first non-ag: field; it may sit anywhere but usually comes first
Unknown keys	kept, never an error — reserved for future versions
Inside tables	the pipe must be escaped as | or it splits the cell

The ten parameters

Parameter	Values	Effect	Applies to
ag:layout	auto gallery float center	override automatic layout	single image
ag:side	left right center	pick a side; center does not float	single image
ag:width	10%–100%	fixed column percentage, 100% means full width, centred	single image
ag:gap	0–80 (px optional)	gap between a floated image and the text	floated images only
ag:crop	W:H	frame ratio, showing only part of the source	single image, tables
ag:top	x1:x2:y (each 0–100)	horizontal span and vertical start of the crop frame	requires ag:crop
ag:isolate	flag / =false	take this image out of the gallery and split the groups around it	anywhere
ag:exclude	flag / =false	hand the image back to Obsidian entirely	anywhere
ag:rows	3,2	hand-written row split: how many images each row holds from the group's first image; the rest is packed	galleries
ag:group	flag / positive integer / =false	lock a row together; adjacent rows need different ids	galleries

The same set of parameters controls layout, width and float side.

Parameter by parameter

ag:layout

Overrides the automatic decision. Four values:

• auto — default, width routing decides.
• gallery — treat as a gallery even when there is only one image.
• float — float even when the width exceeds floatMax.
• center — force a centred block, never float.

ag:side

Picks the horizontal position. left and right float; center equals ag:layout=center. A template's floatAlignment only decides which side is used when no side is given; an explicit side wins.

ag:width

A fixed column percentage, valid range 10%–100%. Once present the routing curve is skipped, but the float test still runs — above floatMax the image is centred anyway. So ag:width=95% produces a centred wide image, not a floated one.

ag:gap

Only affects the gap between a floated image and adjacent body text, in px, the px suffix optional. It has no effect on gallery cell spacing — that value lives in the settings.

ag:crop

A frame ratio such as 1:1, 16:9 or 24:17. It decides the shape of the frame, not its position; position comes from ag:top. The cropped ratio feeds width routing, so cropping changes how wide the image appears on the page.

ag:top

Three numbers in x1:x2:y, each 0–100:

Field	Meaning
x1	left edge of the frame, as a percentage of the source width
x2	right edge
y	top edge, as a percentage of the source height

Only one vertical number is needed because the height follows from the ag:crop ratio. Swapped edges are corrected, out-of-range values are clamped.

Without ag:crop, ag:top is dropped the next time parameters are rewritten — a frequent trap.

ag:isolate

A flag: ag:isolate or ag:isolate=true. The image leaves the current gallery and splits the groups before and after it, so those images no longer merge. The caption stays and the plugin still computes the width.

ag:exclude

Hands the image back to Obsidian completely: no width, no caption, no gallery. Use it when you want to control that image with your own HTML.

ag:rows

Written on the first image of the group, a comma-separated list of segment lengths such as 3,2. It describes the opening rows only: counts are consumed in order, the last one is truncated at the end of the group, and the remaining images are packed automatically — six pictures with 4,3,1 give "four, two", with 2,3 give "two, three, one (packed)". No picture is lost, and no gesture ever writes it. A named row skips the minimum row height and is not bound by the max-per-row ceiling.

ag:group

A flag or a positive integer. Consecutive images sharing an id lock into one row; adjacent rows must use different ids or they merge.

Deprecated keys

fit, focus and a bare top no longer do anything, but are preserved in the source. Use ag:crop and ag:top instead.

Where each parameter applies

Parameter	Gallery	Single	List	Table	Callout
ag:layout	ignored	yes	no	no	no
ag:width	ignored	yes	yes	no	no
ag:side	ignored	yes	no	no	no
ag:gap	ignored	yes	no	no	no
ag:crop	yes	yes	yes	yes	no
ag:top	yes	yes	yes	yes	no
ag:isolate	yes	yes	yes	no	no
ag:exclude	yes	yes	yes	yes	no
ag:rows	yes	—	no	no	no
ag:group	yes	—	no	no	no

Next

• Cropping
• Nested scopes: why only cropping works inside tables

Related

• Cropping
• Nested scopes
• Dialog and reset