# 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.](https://help.gocapable.com/images/43948d2d-b560-42f7-8e4c-1125bef67e89.webp)

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.](https://help.gocapable.com/images/7343cb7f-2288-4fb3-a68a-c0fc4fc3ae47.webp)

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](https://help.gocapable.com/diagrams/troubleshooting.html) 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.

---

## Related

[Diagram engine versionsWhich engine draws what, and what is pinned.](https://help.gocapable.com/diagrams/diagram-engine-versions.html)

[File types and extensionsWhat we recognise, and how the language is decided.](https://help.gocapable.com/diagrams/file-types-and-extensions.html)

[ExamplesWorking diagrams you can copy.](https://help.gocapable.com/diagrams/examples.html)

---

_The page you only need when something is odd._