Excalidraw Whiteboard & Mermaid for Confluence – Guide
How to use Excalidraw for Confluence: a whiteboard on a page, Mermaid diagrams from text, shared scenes, the space page, history and PDF export.
Excalidraw puts a whiteboard inside a Confluence page. You draw boxes and arrows by hand, or paste a few lines of text and get a finished diagram. Everyone who can view the page sees the drawing, and it goes into PDF and Word exports.
How to read the pictures. Every screenshot comes from a real Confluence site. The red boxes with numbers show where to look or click. Number 1 in the picture is step 1 in the text, number 2 is step 2, and so on.
Get started in 2 minutes
- Install Excalidraw from the Atlassian Marketplace. You need to be a Confluence admin. It is free for up to 10 users.
- Edit a page and type /Excalidraw, or open your space’s Excalidraw page and choose All diagrams → New diagram.
- The editor opens over the page: draw with the hand-drawn tools, or choose Insert diagram → Mermaid. The dialog opens with a ready example; press Insert.
- Save. The diagram shows on the page for everyone who can view it.
Add a diagram to a page
- Edit the page, put the cursor where the diagram should go and type /Excalidraw.
- Choose Excalidraw in the menu (or press Enter). You can also find it under + → Apps.
The editor opens at once, over the page:
- Name the diagram, so you find it later.
- Draw with Excalidraw’s tools: shapes, arrows, lines, freehand, text and images. Over 200 shape libraries are under Library; they ship inside the app.
- Insert diagram turns text into a diagram (see Mermaid diagrams from text).
- Press Save, then publish the page.
- The diagram sits in the page like a picture. Readers can Expand it and zoom with − / + / Fit.
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.
The editor: name, Insert diagram, update by name
The editor has one bar on top:
- Name: the diagram’s name.
- Insert diagram ▾: Mermaid, PlantUML, LaTeX Math, Graphviz, Vega-Lite or WaveDrom from text.
- 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.
- The save state (“Saved · version 1” or “Unsaved changes”), History, Save and Close. Save is active only after a change; everywhere the diagram is shown, the new version appears.
Mermaid diagrams from text

Choose Insert diagram → Mermaid.
- Start from an example: Flowchart, Sequence or Mind map.
- Change the Source. Each line is one step or arrow, for example
Check -- Yes --> Done. - The Preview redraws as you type (Fit or 100 %). A mistake shows the reason instead of a picture.
- Give the diagram a name. You find it by this name in Update later.
- Press Insert.
It draws 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. Then annotate by hand: circle what matters, add notes and arrows. How to get Mermaid on a page in other ways, and the errors that stop a diagram: Confluence Mermaid diagrams.
Other diagram types in the same scene
- LaTeX Math: equations typeset with MathJax as sharp vector images. A mistake shows the reason (“Missing close brace”) instead of a broken image.
- Graphviz: graphs in Graphviz DOT with automatic layout: dependency and call graphs, clusters, state machines.
- PlantUML: UML from text with the official PlantUML engine: sequence, class, activity, use case and state diagrams, and C4 architecture diagrams.
- Vega-Lite: bar, line and pie charts from data you paste into the spec. The chart never loads data from a URL.
- WaveDrom: digital timing diagrams: clocks, data lines and bus groups.
PlantUML and C4 diagrams
- In the editor, open Insert diagram ▾ and choose PlantUML (second in the list).
- Pick an example: Sequence, Class, Activity, Use case, State or C4 container.
- Edit the text.
@startumland@endumlare optional, and labels can use any script, Cyrillic included. The preview redraws as you type. - Give it a name if you want to find it in Update later, then Insert.
C4 is built in. !include <C4/C4_Context>, <C4/C4_Container>, <C4/C4_Component> and the other C4-PlantUML files, and the same files linked from GitHub (raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/…), are drawn from C4-PlantUML 2.14.0 inside the app. Any other !include is refused: “External includes are not supported: everything stays inside Atlassian.”
Errors. A mistake shows as a message with the line in your own text, for example “PlantUML: Syntax Error? (Assumed diagram type: sequence) on line 2.” Insert stays off until the text draws.
The space page: On this page and All diagrams
- In the space sidebar, under Space apps, click Excalidraw.
- The page has two tabs: On this page (the diagram shown on the space page) and All diagrams.
- With no diagram yet, Choose a diagram picks one from All diagrams.
- New diagram draws a diagram that does not belong to one page.
- Narrow the list: All, Global (the whole site) or This space, sorted by Last edited. The search box finds a diagram by name.
- Each card shows a 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 the diagram 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.
Show a shared scene in a macro
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.
View settings
In the page editor, the macro’s View settings (max height of 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.
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, with no diagram server.
- PlantUML and C4: the PlantUML engine (
@plantuml/core1.2026.9) and C4-PlantUML 2.14.0 ship inside the app and load only when a PlantUML diagram is shown or edited. Nothing is fetched from plantuml.com, GitHub or any other 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.
Related apps
- Excalidraw Whiteboard & Mermaid Diagrams for Jira: the same app for Jira.
- Excalidraw Math Equations & LaTeX Whiteboard for Confluence: LaTeX Math first.
- Excalidraw Architecture & Sequence Diagrams for Confluence: Graphviz first.
- PlantUML Diagrams: UML & C4 for Confluence – Excalidraw: PlantUML and C4 first.
Further reading
- Confluence Excalidraw: 12 apps and where your drawing lives: every Excalidraw app for Confluence by price, permissions and what happens to drawings on uninstall.
- Confluence Mermaid diagrams: 5 ways, 53 apps compared: how to get Mermaid on a page without an app, with the free Atlassian Labs viewer or a macro; six page templates and the errors that stop a diagram.