Mermaid 12.3 in Confluence: five new diagram types
Mermaid 12.3 is now live in Mermaid Plus Diagrams & AI Agent for Confluence, and with it come five new diagram templates in the app: Wardley strategy maps, event modeling flows, BPMN process shapes, animated step-by-step flows, and agent workflow diagrams. Each one closes a specific documentation gap that used to force teams into a separate drawing tool — or into whiteboard photos nobody could update.
Quick answer: Mermaid 12.3 adds BPMN element shapes for flowchart nodes, step animation on flowchart edges, and new edge markers — and Mermaid Plus pairs the engine bump with five new templates: Wardley maps (wardley-beta) for build-vs-buy planning, event modeling (eventmodeling) for event-driven design sessions, BPMN process notation for process audits, animated flows for onboarding and runbooks, and agent flows (agentflow-beta, which landed in Mermaid 12.0 and was still missing from most editors) for documenting AI workflows. Type /mermaid+ on a page, pick a template from the middle panel, and the diagram renders as you edit. Existing diagrams keep working and upgrade themselves on next view.
Which diagram solves which problem
| You are... | Use | The problem it solves |
|---|---|---|
| Planning a roadmap or arguing build-vs-buy | Wardley map | Strategy debates re-litigated every quarter because nobody shares a picture of what is commodity vs novel |
| Designing an event-driven feature with stakeholders | Event modeling | Whiteboard photos die in Confluence; the UI → command → event flow isn't reviewable by anyone who missed the session |
| Documenting a business process for auditors or ops | BPMN shapes | Free-form flowcharts don't read as official process; drawing-tool BPMN goes stale the week after the workshop |
| Onboarding new hires or writing incident runbooks | Animated flow | A 10-arrow diagram makes readers guess where to start and which path is "the" happy path |
| Shipping an AI agent that others must review | Agent flow | Agent workflows live in stale slides; security and compliance need to see exactly what the agent reads, calls and hands off |
What's new in Mermaid 12.3 (and what the app picks up)
| Change | What it means for your pages |
|---|---|
Wardley maps (wardley-beta) | Strategy maps as text: components on a visibility × evolution grid, evolve arrows, build/buy/outsource decorators |
Event modeling (eventmodeling) | Event-driven system flows on an inferred UI / Command / Events timeline, written with numbered time frames |
| BPMN element shapes | Flowchart nodes can now render as real BPMN notation — events, gateways, activities, data objects, data stores, annotations |
Step-by-step flow animation (e1@{ step: 1 }) | Edges play in order with a traveling dot — handy for request walkthroughs (disabled automatically for reduced-motion readers) |
Agent workflows (agentflow-beta) | Document AI agents as text: a flow block per agent with typed steps, connector blocks for the external systems it calls |
| New edge markers | Open-arrow and hollow-circle heads, so a notation can tell two kinds of flow apart |
| Backward compatible | Existing diagram code renders unchanged; layout and styling may shift subtly |
Wardley maps: strategy as text
A Wardley map answers a question that requirement docs keep losing: which parts of our value chain are commodities now, and which are still novel? Writing it in Mermaid means the map lives next to the PRD instead of in a screenshot.
Paste this into a Mermaid+ macro (or start from the Wardley template in the panel):
wardley-beta
%% coordinates are [visibility, evolution]
title Tea Shop Value Chain
%% anchor: a user or business need (bold label)
anchor Business [0.95, 0.63]
%% component: a capability on the map; (build)/(buy) are strategy decorators
component Cup of Tea [0.79, 0.61]
component Tea [0.63, 0.81] (build)
component Hot Water [0.52, 0.80]
component Kettle [0.43, 0.35] (buy)
component Power [0.10, 0.70]
%% dependencies point from consumer to dependency (A -> B: B depends on A)
Business -> Cup of Tea
Cup of Tea -> Tea
Cup of Tea -> Hot Water
Hot Water -> Kettle
Kettle -> Power
%% evolution arrows: where a component is heading
evolve Kettle 0.62
evolve Power 0.89
note "Standardising power allows Kettles to evolve faster" [0.30, 0.49]
Reading it back: coordinates are [visibility, evolution] — visibility on the Y axis (0 = invisible infrastructure, 1 = directly user-facing), evolution on the X axis (0 = genesis, 1 = commodity). Red dashed arrows come from evolve, which marks where a component is heading. Dependencies link the value chain downward: the business needs the cup of tea, which needs power — and power is already a commodity, which is why you never build it. Other strategy decorators — (outsource), (market), (inertia) — go in the same spot as (build)/(buy).
Wardley maps in practice: the quarterly build-vs-buy review
A platform team walks into roadmap planning with three competing proposals for the same authentication work. Without a shared picture, the debate repeats every quarter. With a Wardley map on the space's tech-radar page, the argument settles in one glance: identity management sits far right (commodity — buy it, integrate it), while the usage-based pricing engine sits far left (genesis — nobody has productized this, building it is the differentiator). The map becomes the pre-read for the planning meeting; when a component evolves — say a vendor ships a solid feature-flag product — you move it and add an evolve arrow, and the page history shows when the strategy changed and why. That is the part a whiteboard photo can never do.
Event modeling: the system-behavior timeline
Event modeling describes systems by how information flows through them — user interface, command, event, read model — usually drawn on a big whiteboard. Mermaid 12.3's eventmodeling type brings that workflow into text, with swimlanes inferred for you:
eventmodeling
tf 01 ui CartUI
tf 02 cmd AddItem
tf 03 evt ItemAdded
tf 04 rmo CartItems
tf 05 ui CartUI
Each tf (time frame) gets a unique number and an entity type: ui, cmd (command), evt (event), rmo (read model) or pcr (processor). Entities land in the UI/Automation, Command/Read Model and Events swimlanes automatically, and the flow between frames is inferred — so you sketch the timeline and mermaid wires it. When inference guesses wrong, a reset frame (rf 04 evt ...) breaks the chain, and ->> reconnects frames explicitly.
Event modeling in practice: design sessions that survive the meeting
An order-fulfillment feature kicks off with a two-hour design session: what does the customer see, what command does it trigger, what event fires, what read model does the next screen need? In the room, that is a whiteboard. The problem starts when the meeting ends — the photo lands in a page, nobody can comment on a specific step, and three sprints later the implemented behavior has quietly drifted. Typed into Confluence with eventmodeling, every frame is a reviewable line: the product reviewer asks about tf 03 in page comments, the engineer edits tf 05 when the design changes, and the diff shows up in page history. A pcr frame marks pure processing (no UI), and an rf reset marks manual steps where automatic inference would guess wrong — exactly the spots a reviewer needs to look at.
BPMN shapes: process notation without the plugin
The other headline in 12.3: flowchart nodes can now be rendered as genuine BPMN notation. The full shape catalog, in one process:
%% bpmn-start: thin circle · bpmn-intermediate/boundary: double circles
%% bpmn-end: thick circle · bpmn-gateway: diamond · bpmn-activity: task box
%% bpmn-data: document · bpmn-data-store: cylinder · bpmn-annotation: bracket
flowchart TB
start@{ shape: bpmn-start, label: "Start" }
task@{ shape: bpmn-activity, label: "Do work" }
bound@{ shape: bpmn-boundary, label: "Timeout" }
mid@{ shape: bpmn-intermediate, label: "Message in" }
gw@{ shape: bpmn-gateway, label: "OK?" }
data@{ shape: bpmn-data, label: "Doc" }
store@{ shape: bpmn-data-store, label: "DB" }
ann@{ shape: bpmn-annotation, label: "SLA 24h" }
endN@{ shape: bpmn-end, label: "End" }
start --> task
task -.-> bound
bound -.-> task
task --> mid
mid --> gw
gw -->|yes| endN
gw -->|no| task
task --> data
data --> store
ann -.-> task
Edges stay standard flowchart arrows, so existing flowchart habits carry over. And because they are ordinary flowchart edges, BPMN processes can also use the step animation from the next section.
BPMN in practice: refund processes auditors can read
Refund and chargeback handling is the classic case: support knows the steps, finance knows the controls, and the audited "official process" lives in a Visio export nobody has opened since last year's audit. Drawn with BPMN shapes in Confluence, the same process becomes maintainable text — the gateway is a real diamond, timeouts are bpmn-boundary events hanging off the activity, the SLA note is a bpmn-annotation, and the system of record is a bpmn-data-store. An external auditor reads the notation without a legend; an ops engineer updates the gateway condition in four lines of text after the policy change; and because it renders from source, the page always shows the process as it actually is — not as it was in the screenshot. The same pattern works for SOPs, onboarding checklists, and any flow where "which symbol is which" carries meaning.
Animated flows: a walkthrough that plays itself
The other 12.3 headline is step animation for flowchart edges. Give each edge an id, then number the steps:
%% name each edge with an id: nodeId@--> ; set the play order with id@{ step: N }
flowchart LR
Requester e1@--> Approval
Approval e2@--> Finance
Finance e3@-->|approved| Payment
Payment e4@--> Requester
e1@{ step: 1 }
e2@{ step: 2 }
e3@{ step: 3 }
e4@{ step: 4 }
In the editor and on the page, the edges highlight in step order while a dot travels along the active one — the image above is the animated SVG itself, so if it is moving in your browser, that is exactly what a Confluence reader sees. Readers with reduced-motion preferences get a static diagram automatically, and flowchart.stepDuration (milliseconds per step, set in the YAML frontmatter at the top of the code) tunes the pace.
Animated flows in practice: runbooks that point at the next step
Picture the two audiences where this pays off immediately. New hires onboarding into a request-approval-payment workflow don't squint at ten arrows wondering where to start — the diagram plays the happy path in order, and the loop from Payment back to Requester explains itself. Incident responders at 3 a.m. get a runbook diagram whose escalation path walks itself: detection → page the on-call → mitigate → communicate, each edge lighting up in sequence, with branch edges (rollback vs. hotfix) waiting un-highlighted until relevant. Because the animation is part of the rendered SVG on the page — not a video to maintain — the runbook stays a normal Confluence page that edits as text.
Agent flows: document AI agent workflows as text
Agent diagrams are no longer an afterthought. agentflow-beta (new since Mermaid 12.0, and now a template in the app) draws agentic workflows — one flow block per agent, typed steps inside, and connector blocks for the external systems the agent talks to:
agentflow-beta TB
%% one flow block per agent; the shaded group is the agent itself
%% type each step as input (parallelogram), task (rounded box) or tool (boxed bar)
flow reviewer["Review Agent"]
changes["Gather changes"]@{ shape: input }
analyse["Analyse"]@{ shape: task }
lint["run_linter"]@{ shape: tool }
changes --> analyse --> lint
end
%% connector: an external system or human in the loop; edges and edge
%% labels (-->|approved|) work exactly as in flowcharts
connector ext["External system"]
reviewer -->|approved| ext
This is the shape of a code-review agent: gather the changes, analyse them, call the linter tool, and — once approved — hand the result to an external system. When the workflow changes, you edit four lines of text instead of re-drawing a swimlane diagram.
Agent flows in practice: the security review conversation
Before an AI agent ships, someone has to answer hard questions: what data does it read, which tools does it call, what leaves the boundary, where is the human approval? With slides, those answers are stale the week after the demo. With an agent flow on the Confluence page, the security review has an artifact to point at: the flow block is the agent's boundary, @{ shape: tool } steps are exactly the actions it can take, and connector blocks are the systems it hands off to — reviewers sign off per connector, not per slide. The same page then serves as the agent's living documentation: when the workflow gains a step, the diff in page history shows the boundary change, which is precisely what an AI-governance review wants to see.
What your existing diagrams will do
Nothing dramatic, by design. The 12.3 engine upgrade is backward compatible syntactically — your flowcharts, sequence diagrams, gantt charts and mind maps keep rendering as before. What you may notice:
- Diagrams upgrade themselves — the macro re-renders with the new engine the next time the page is viewed, and the refreshed SVG is cached on the next edit. No migration, no action.
- Swimlane and ELK routing fixes land with 12.3, so some lane diagrams may route their edges more cleanly than before.
- Use case include/extend labels now render with proper UML guillemets (
«include»).
Where to find the new templates
| App | Where |
|---|---|
| Mermaid Plus Diagrams & AI Agent for Confluence | Insert the macro → Quick Templates panel → Wardley / Event Modeling / BPMN / Animated Flow / Agent Flow, or the Help modal for syntax examples |
| Enhanced Markdown for Confluence | Type a ```mermaid fence with wardley-beta, eventmodeling, agentflow-beta or a @{ shape: bpmn-… } flowchart |
The Rovo AI agent in Mermaid+ knows every Mermaid v12 diagram type, so you can ask for a Wardley map in chat and have it inserted onto the page directly.
Related posts
- Mermaid 12 in Confluence & Jira: UML use case diagrams and a new look
- UML use case diagrams in Confluence
- Mermaid vs PlantUML vs Graphviz in Confluence
Try Mermaid Plus Diagrams & AI Agent for Confluence
All 30 Mermaid diagram types plus a Rovo AI agent, with live preview and one-click templates — free for up to 10 users.
Get it on the Atlassian Marketplace