Diagram macro reference

The diagram macro has more settings than most people ever open, because the defaults are right for most diagrams. This is the full list for the times they are not.

Almost every visual setting can be set to inherit, which takes the value from the space setting. That is how you change every diagram in a space at once.

#When you need this page

A diagram that is the wrong size, or scrolls oddly.
Setting a space-wide default and wanting to know what each option means.
Pinning a diagram to a specific version.

#The detail

The Inserting Diagram Reference dialog with a BPMN purchase order approval diagram on the left and Template, Height and Show Border fields on the right. — A reference to an existing template exposes the same height and border fields, next to a preview of what the page will show.

Field	What it does
Title	Shown above the diagram, and used in search results.
Height	Fixed height in pixels. Ignored when proportional or classic sizing applies.
Display mode	How the diagram is sized and scaled. See the table below.
Alignment	Left, centre or right, within the macro container. Only Auto and Classic have room to move.
Dark mode	Inherit, enabled or disabled. Inherit follows the space setting and the reader's theme.
Proportional	Auto-height: the container grows to fit the diagram instead of scrolling.
Scrollable	Native scrollbars instead of pan and zoom. Good for very wide diagrams.
Smart Scale	Proportional scaling, so a small diagram is not blown up to fill the width.
Options	Show Border draws a frame around the diagram.
Diagram version pin	Renders a specific stored version rather than the latest.

#Display modes

A Diagram Reference macro selected in the Confluence editor, with a floating toolbar offering edit, a Centered alignment menu, copy and delete. — Selecting the macro in the editor reveals the toolbar that sets how it sits on the page.

Mode	What it does	Use when
Auto	Proportional sizing with scrollbars when needed	The default, and right for most diagrams
Fixed	Pan and zoom inside a fixed-height box	The diagram is large and readers will explore it
Max	Proportional, expanded to the full column width	A wide diagram that should fill the page
Classic	Natural size, left aligned, box hugs the diagram	draw.io parity, and small diagrams that should stay small

If a diagram looks clipped, start here. Display mode is the setting behind almost every sizing complaint. Troubleshooting has the full decision tree.

#A few things that catch people out

Inherit is not a value, it is a deferral. Changing the space setting moves every inheriting macro.
Height is ignored by the modes that size themselves. Setting it and seeing nothing change is expected.
Alignment does nothing in Fixed and Max, because those already span the column.

Diagram engine versions

Which engine draws what, and what is pinned.

File types and extensions

What we recognise, and how the language is decided.

Examples

Working diagrams you can copy.

The page you only need when something is odd.