Core concepts
Every behaviour in the plugin follows from these five rules. Once they are clear, most "why didn't it work" questions answer themselves.
1. Grouping reads the source, not the screen
The plugin looks at the lines an image occupies in the Markdown source, not at the rendered DOM. Scrolling, zooming and switching views never change which images belong together.
Reading view collapses blank lines, so the visual gap looks identical; but zero, one and two blank lines are three different states in the source, and the third is already the limit. Count blank lines in the source, not pixels on screen.
2. Two or more adjacent images are always a gallery
When a group holds two or more images they enter a gallery: one shared row height, column widths distributed by aspect ratio. At that point ag:layout, ag:width and ag:side written on individual images are all ignored — a row is one unit.
To control a single image, first move it out of the group: separate it with body text or a heading, or write ag:isolate.
3. A single image gets its width from its ratio
With no parameters, the column percentage is a piecewise power function of the aspect ratio: square images get about four tenths (39%), wide images approach full width, portrait images get roughly a third. Two thresholds decide "centred or floated" and "left or right".
Three knobs shift the whole curve: width gain and median ratio in settings, plus template rules.
4. The closer the declaration, the higher the priority
From lowest to highest:
- Global settings (
floatMax,mobileBreakpoint, …) - Rules of the active template
- The specific
ag:parameter written on the image
So no matter how wide a template is, an image with ag:width=40% stays at 40%. Conversely, a template only affects images with no parameters and layout: auto.
5. The container decides what is possible
The same image supports fewer features as the container gets more complex:
| Container | Width / float | Gallery | Crop | Handles |
|---|---|---|---|---|
| Body | yes | yes | yes | yes |
| List item | block layout, width allowed | side by side within one item | yes | no |
| Table cell | no | no | yes | action buttons in Live Preview only |
| Callout | no | no | no | no |
This is deliberate: the more complex the container, the less geometry can be adjusted safely.
Summary
Source decides grouping, ratio decides width, the closest declaration wins.