Live Diagram for Confluence

Show how your system works, right beside the words that describe it.

View and play distributed-system diagrams on Confluence Cloud pages. Press Play to watch messages flow, or replay a saved simulation. The diagram is a page attachment, with the permissions and version history your team already uses. The app is free and open source, published by Live Diagrams.

Install

Atlassian Marketplace: coming soon.

When the listing is available, a Confluence Cloud site admin can install Live Diagram from Marketplace. It supports Cloud only. No separate Live Diagrams account or subscription is needed.

Put a diagram on a page

  1. Make or open your diagram in Live Diagrams. Use File → Export as → Diagram file to download a .diagram.json file. The older .livediagram.json suffix is also accepted. PNG and Interactive HTML files cannot be used here.
  2. Publish the Confluence page first so it can hold attachments. Edit it, type /Live Diagram, and insert the macro.
  3. Choose a diagram attached to this page, or select a local file and choose Upload a new attachment. Files must be valid diagram JSON and no larger than 8 MB.
  4. Choose Free play or a saved simulation, Automatic height or a fixed height, and Follow Confluence, Light or Dark. Save the macro and publish the page.
  5. The diagram starts still. Press Play diagram to start the flow. You can reach it with Tab and press Enter or Space. Use Maximise to open a larger view inside Confluence, then close it to return to the page.

Uploading or replacing a file happens immediately, even if you later cancel macro configuration.

Change a diagram

  1. Download the diagram attachment from Confluence.
  2. Open it in Live Diagrams, make your changes, and export the Diagram file again.
  3. Edit the macro configuration, keep the existing attachment selected, choose the updated file, and click Replace selected attachment. Save and publish.

Replacement keeps the attachment's ID and filename and adds a version to Confluence's history. You can restore an earlier version there. The macro reads the latest version when loaded; reload the page to see a replacement. If you removed the selected saved simulation, choose another one or Free play.

The macro is for viewing and playback. Edit diagrams in Live Diagrams, outside Confluence.

Permissions and privacy

Every reader uses their own Confluence page and attachment permissions. The app cannot bypass them. Uploading and replacing files also requires the appropriate Confluence editing and attachment permissions. The app asks for attachment read access and file upload/replacement access; reading a page does not upload files.

The diagram stays as a Confluence attachment. Macro settings hold only the attachment reference, simulation, height and theme. Viewing and playback run in your browser using Atlassian Forge-hosted resources. There is no separate app storage, analytics, third-party service or external data transfer, and the macro has no outbound link. Data residency follows Confluence for page settings and attachments. Read the Confluence privacy section.

Troubleshooting

No attachments to choose

Publish the page first. Upload a valid .diagram.json or .livediagram.json file to this page, then reopen configuration. A file attached to another page must be uploaded here.

The file will not load

Check your page and attachment access, and ask your admin whether the app is allowed on this page. Export a fresh Diagram file from Live Diagrams and keep it within 8 MB. Renaming an image to JSON does not turn it into a diagram. If the attachment was deleted, select or upload a replacement.

Play does not show traffic

Choose a saved simulation with traffic, or use Free play with a diagram that has traffic sources. Add sources or simulations in Live Diagrams, then replace the attachment. If a simulation is missing, choose an existing one in macro configuration.

The view is too small, or a copied page will not load

Try Automatic height, a larger fixed height, or Maximise. On a copied or moved page, reopen configuration and reselect the attachment if Confluence changed its reference. PDF and Word exports are not supported by this macro.

Support

Report a Confluence app issue on GitHub. Include steps, what you expected, the browser and any error message, with sensitive details removed. Never attach private or work diagrams. Use an invented, generic example and check screenshots for site names, account details and confidential content before posting. Support is public, with no guaranteed response time.

Browse Confluence issues · Terms