Pitfalls

Sixteen conclusions that look like bugs but are design. Look up the symptom; the third column is what to do instead.

#	Symptom	What to do
1	I set ag:gap but gallery cells did not move	ag:gap only widens the gap between a floated image and the text; cell spacing is the "Gallery image gap" setting
2	ag:width on an image inside a gallery does nothing	two or more consecutive images are always a gallery; per-image layout / width / side are ignored. Use ag:isolate or body text to take it out first
3	A single image on its own row still fills the column	a one-image row is still a gallery cell and fills the column; write ag:width, or rely on the orphan rule
4	ag:top disappears after I change another parameter	ag:top requires ag:crop; without a crop it is dropped on the next rewrite
5	ag:width inside a table does nothing	table cells accept only ag:crop and ag:exclude; the table decides the width
6	Two images in a callout are not side by side	callouts are claimed but not decorated; they keep Obsidian's native styling
7	Two adjacent images in a list did not form a row	they are in different list items; side-by-side only happens within one li
8	Text does not wrap beside the image in Live Preview	Live Preview never wraps body text; check wrapping in reading view
9	I left many blank lines and they still sit together	the limit is 2 blank lines; the third one breaks the group. Blank lines are invisible in reading view, which is why it is easy to misjudge
10	I raised the orphan ceiling to 1200 and the portrait still left	the test uses the rendered full-column height, not the file's pixel height
11	ag:width=95% works, but the docs said the limit was 90%	the valid range is 10%–100%; older docs were wrong. 100% means full width, centred
12	A template rule with min(0.6, r) did not apply	only Math.* is allowed; write Math.min(0.6, r). Invalid rules are dropped silently
13	album: Trip in frontmatter does not match the route	routing compares exact strings; Trip ≠ trip. Keep keys and values lowercase
14	A row named by ag:rows ignores the minimum row height	hand-written splits deliberately skip galleryMinHeight, because that is the split you asked for
15	A whole gallery row was split across two PDF pages	it cannot split; what looks like a split is usually two rows misread as one — check blank lines and body text
16	Switching to layout preview shows no page breaks	layout preview is one continuous page; use the paginated preview (which prints a real PDF)

Four more

• The settings page cannot create templates or edit rules. It can only import, export, delete, and change name and float direction. Rules arrive through a .json import.
• Gallery cells have no corner grip. The row decides the width; drag the divider between two cells instead.
• ag:isolate is not ag:exclude. The first still gets plugin layout and keeps its caption; the second is handed back to Obsidian and shows no caption.
• Cropping changes width. The plugin uses the cropped ratio, so cropping to a square narrows the image.

Is it the plugin or me?

1. Put the image in its own paragraph — if behaviour changes, it was a grouping issue.
2. Switch to reading view and look again — if it changes, it was a view difference (wrapping).
3. Check for ag: parameters — a parameter beats the template.
4. Reset the relevant setting to its default — if it changes, it was a setting.

Next

• Annotation syntax
• Settings

Related

• Grouping
• Width routing
• Pagination