# 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. * Working out what a button on the diagram's toolbar does. --- ## 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. --- ## The toolbar on the page Hover over a published diagram and a small toolbar appears. Which buttons show depends on the diagram's language and on what you are allowed to do. | **Button** | **What it does** | | --------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Comment count | The first button, yellow, showing how many comments the diagram has (**100+** past 100). Select it to open the diagram full screen with the comments open. It only appears once a diagram has comments. See [Comments on diagrams](https://help.gocapable.com/diagrams/comments-on-diagrams.html). | | **Decrease size** and **Increase size** | Zoom the diagram inside its box. Not shown for Excalidraw, or in display modes that size the diagram for you. | | **Edit diagram** | Opens the editor. Only shown to people who can edit the diagram. | | **Toggle dark mode** | Switches the diagram between light and dark rendering when Confluence is in dark mode. | | **Download diagram** | Downloads the rendered SVG. For draw.io it reads **Download diagram as PNG**. Not offered for Excalidraw, BPMN or DMN; use the full-screen view to export those. See [Export a diagram](https://help.gocapable.com/diagrams/export-a-diagram.html). | | **Maximize** | Opens the diagram full screen, with download, share and **Comments** buttons. | --- ## 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. * The comment count does not refresh by itself. It updates when you close the full-screen view, or when the page reloads. --- ## Related ### [Diagram engine versions](https://help.gocapable.com/diagrams/diagram-engine-versions.html) Which engine draws what, and what is pinned. ### [File types and extensions](https://help.gocapable.com/diagrams/file-types-and-extensions.html) What we recognise, and how the language is decided. ### [Examples](https://help.gocapable.com/diagrams/examples.html) Working diagrams you can copy. ### [Comments on diagrams](https://help.gocapable.com/diagrams/comments-on-diagrams.html) What the comment count opens. --- _The page you only need when something is odd._