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.

Get started in 2 minutes

  1. Install Excalidraw Graphviz from the Atlassian Marketplace (a Confluence admin; free for up to 10 users).
  2. Edit a page, type /Excalidraw and publish — or open your space’s Excalidraw Graphviz page and choose All diagrams → New diagram.
  3. The editor opens over the page: draw with the hand-drawn tools, or choose Insert diagram → Graphviz — the dialog opens with a ready example — and press Insert.
  4. Save. The diagram shows on the page for everyone who can view it.

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 diagram → Graphviz opens the dialog with an example already in it: the source, a live preview (Fit or 100 %) and the diagram’s name. 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, open Update ▾ — it lists the canvas’s diagrams by name — or select the diagram and press Update “its name”, then 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.

The editor: name, Insert diagram, update by name

Since November 2026 the editor opens over the page with one bar on top: the scene’s Name, Insert diagram ▾, Update ▾, the save state (“Saved · version 4” or “Unsaved changes”), History, Save and Close.

  • Insert diagram opens the chosen type’s dialog with an example already in it and a field for the diagram’s name, so the first diagram takes one click.
  • Update ▾ lists the diagrams on the canvas by name. Select one on the canvas and the button becomes Update “its name”; the dialog opens on its source.
  • Save is active only after a change and asks once: everywhere the diagram is shown, the new version appears; earlier versions stay in History.

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: On this page and All diagrams

Every space has an Excalidraw Graphviz page in its navigation with two tabs:

  • On this page — the diagram shown on the space page. With none yet it says “No diagram on this space page yet” and offers Choose a diagram.
  • All diagrams — New diagram, a search, the filters All, Global and This space, a sort (Last edited), and a card per diagram: its preview, where it lives, when and by whom it was edited, and on which page it is shown (“Not shown anywhere yet” otherwise). Open shows it full screen with its name, Edit and ×; Edit opens the editor; ⋯ → Show here puts it on the space page.

The global page (Apps → Excalidraw) lists every diagram on the site with the same search and filters. Delete asks first: the diagram disappears from every page that shows it, so this cannot be undone. A space diagram 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 lists the last 10 saved versions. Restore saves an old version as a new one, so the current version stays in the list.
  • 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.