SimplifyInstall apps

Excalidraw Architecture Diagrams for Confluence – Guide

How to use Excalidraw Graphviz for Confluence: DOT graphs and Mermaid sequence diagrams in design docs and runbooks, history, PDF export and permissions.

Overview

Excalidraw Architecture & Sequence Diagrams for Confluence lets you write architecture graphs in Graphviz DOT and sequence diagrams in Mermaid on Confluence pages, then sketch around them on an Excalidraw whiteboard — for design docs and runbooks.

A diagram is an Excalidraw scene. It can live in three places:

  • a macro on a page or blog post — the page’s own diagram, or a shared scene shown there;
  • the space page — the space’s scenes, one of them shown on the page;
  • the global page (Confluence’s Apps menu) — every scene on the site.

Diagrams from text are built in: Graphviz, Mermaid, LaTeX Math, Vega-Lite, WaveDrom. The source of each stays with the diagram, so you can change it later. Everything runs on Atlassian Forge: scenes are stored in your Atlassian site and rendered in your browser; the app makes no external calls.

Install

Install Excalidraw Architecture & Sequence Diagrams for Confluence from the Atlassian Marketplace. A Confluence admin approves the permissions.

Add a diagram to a page

  1. Edit the page and type /Excalidraw Graphviz (or choose it from + → Apps). The macro Excalidraw Graphviz is added where the cursor is.
  2. The empty macro says “Draw a diagram for this page”. Press Create diagram and the editor opens.
  3. Draw with Excalidraw’s tools — shapes, arrows, freehand, text, images — and over 200 shape libraries under Library, which ship inside the app. Save stores the scene.

Each macro is its own diagram: a second macro on the page is a second diagram, and a copy of the page gets its own copy of the diagram, so changing the copy never changes the original.

Graphviz diagrams from text

Insert → Graphviz opens the Graphviz dialog: a name, the source and a live preview. Start from an example — Directed graph, Clusters and State machine — or type your own. It draws graphs in Graphviz DOT with automatic layout: dependency and call graphs, clusters, state machines.

Any Graphviz layout engine works: put a line such as layout=neato; or layout=twopi; at the top of the graph. Our guide Graphviz in Confluence shows what each engine draws, with five templates to copy.

Insert places it in the scene. To change it later, Update → Graphviz, pick the diagram on the canvas and edit the source: the diagram keeps its place and scale.

Then annotate by hand: circle what matters, add notes and arrows. Select an element to change its colour, font, size or layer in the panel on the left.

Other diagram types in the same scene

  • Mermaid — flowcharts, sequence, class, state and ER diagrams, Gantt charts, mind maps and timelines (Mermaid 11). Insert as shapes turns a Mermaid diagram into ordinary Excalidraw shapes you can move and restyle one by one. Examples: Flowchart, Sequence and Mind map.
  • LaTeX Math — equations typeset with MathJax as sharp vector images: fractions, matrices, aligned equations, sums and integrals. A mistake shows the reason (“Missing close brace”) instead of a broken image. Examples: Quadratic formula, Matrix, Series and Aligned.
  • Vega-Lite — bar, line and pie charts from data you paste into the spec. The chart never loads data from a URL. Examples: Bar chart, Line chart and Pie chart.
  • WaveDrom — digital timing diagrams: clocks, data lines and bus groups. Examples: Clock and data, and Bus groups.

Show a shared scene on a page

A shared scene is one diagram shown on many pages; a change to it shows on all of them. To show one in a macro, edit the page, open the macro’s settings and choose it under Scene (“Scenes of the whole site and of this space”). Leave Scene empty to keep the macro’s own diagram.

The space page and the global page

The Excalidraw Graphviz space page (in the space’s navigation) has a View tab with the scene attached to the space, and a Scenes tab: Create a new scene, the Scene picker with Preview, Edit and Attach, and every scene of the space as a card — when it was edited and on which page it is shown.

The global page (Apps → Excalidraw Graphviz) lists every scene on the site with a search and a filter. Delete asks first: the scene disappears from every page that shows it, so this cannot be undone. A space scene can be deleted by its author or a space admin.

View settings

In the page editor, the macro’s View settings — max height (at least 120 px), Fit diagram, Match Atlassian theme, zoom and position — apply to everyone who views the page. Scroll inside the diagram lets the mouse wheel move the diagram; Ctrl/⌘ + wheel zooms. Readers can Expand the diagram and zoom with − / + / Fit.

Saving, history and conflicts

  • Version history: History in the editor keeps the last 10 saved versions; Restore saves an old one as a new version.
  • Two people at once: if someone saved while you were editing, nothing is overwritten. Your changes stay in the editor and you choose to merge them with the latest version (for each shape the newer edit wins), reload, or save yours as a copy.
  • Unsaved work survives a closed tab: the editor offers to restore it next time.
  • Size: up to 5 MB per scene, images included; the meter in the editor shows how much is used.

PDF and Word export

Exporting the page to PDF or Word includes the diagram as it appears on the page — text diagrams, hand-drawn notes and charts.

Permissions and data

  • Who can change a diagram: changing a macro’s diagram needs permission to edit the page; a space’s scenes need permission to create pages in that space. Everyone who can view the page sees the diagram.
  • Scopes: the app asks only to read spaces and pages, and for its own storage.
  • Where data lives: scenes, images and sources are stored in the app’s Forge storage inside your Atlassian site. Diagrams render in your browser; Mermaid, MathJax, Graphviz, Vega-Lite and the shape libraries ship inside the app — no PlantUML or other diagram server.
  • Cyrillic, Chinese and other scripts work; light and dark themes.

See the privacy policy.

Troubleshooting

  • “No scene chosen” — edit the page, open the macro’s settings and choose a scene, or leave Scene empty and draw the macro’s own diagram.
  • “The diagram could not be loaded.” — press Try again.
  • Insert is disabled in a text dialog — the preview shows the error; fix the line it names.
  • “This scene no longer exists” — the shared scene was deleted; choose another one.
  • “Excalidraw needs an active licence” — a Confluence admin renews it in Manage apps.

Still stuck? Contact support.