Mermaid 12 in Confluence & Jira: UML Use Case Diagrams and a New Look
Mermaid 12 is the biggest release the diagram language has had in years — and as of today it is live in all three NGPILOT diagram apps: Enhanced Markdown for Confluence, Mermaid Plus for Confluence, and Mermaid Plus Diagrams for Jira. You get the headline feature immediately: UML use case diagrams, the diagram type Confluence and Jira teams have been asking for since requirements documents moved out of dedicated UML tools.
Quick answer: Mermaid 12 adds UML use case diagrams (usecase-beta), a new default layout engine (ELK), and refreshed diagram styling — and all three NGPILOT diagram apps already run it. In Enhanced Markdown for Confluence, type a ```mermaid fence with usecase-beta; in Mermaid Plus for Confluence and Mermaid Plus Diagrams for Jira, paste the same syntax into the diagram panel. Existing diagrams keep working unchanged.
What's new in Mermaid 12
| Change | What it means for your pages |
|---|---|
UML use case diagrams (usecase-beta) | The missing UML diagram type: actors, use cases, system boundaries, include/extend, notes — as text |
| ELK as the default layout engine | Cleaner automatic layouts, especially for dense flowcharts and state machines |
| Refreshed default look | New color palettes and styling for flowchart, state, and class diagrams |
| Backward compatible | Existing diagram code renders unchanged; layout and colors may shift subtly |
The headliner: use case diagrams as text
A use case diagram answers one question: who does what with the system, and what does what depend on what? Until now, answering it in Confluence or Jira meant a drawing tool. With Mermaid 12 it's a code block — which means it's editable, diffable, and lives with the ticket or page it documents.
Paste this into an Enhanced Markdown mermaid fence or a Mermaid Plus panel:
usecase-beta
direction LR
actor Customer
actor Admin
systemBoundary Store("Online Store")
UC1("Browse Products")
UC2("Checkout")
end
Customer --> UC1
Customer --> UC2
Admin --> UC2
UC2 ..> : include UC1
Admin --|> Customer
note for UC1 "Available 24/7"
Reading it back: two actors, one system boundary, two use cases inside it. UC2 ..> : include UC1 says checkout always includes browsing the catalog; Admin --|> Customer makes Admin a specialization of Customer. The note pins operational detail to the use case it belongs to.
Syntax pieces worth knowing:
actor Name— a person or external systemsystemBoundary Id("Label") ... end— groups the use cases of one systemUC("Label")— a use case (an ellipse in the render)-->association,..>include,--|>generalizationnote for UC1 "text"— annotation attached to a use case
Because it's Mermaid — text, not a canvas — updating the flow when requirements change is a one-line edit, and the diagram re-renders with the page.
What your existing diagrams will do
Nothing dramatic, by design. Your flowcharts, sequence diagrams, gantt charts, and mind maps keep rendering exactly as before, syntactically. What you may notice:
- Layouts shift slightly in dense graphs — ELK can route edges differently (usually better)
- Default colors are refreshed — if your diagrams rely on default theming, they may read a touch differently; explicitly themed diagrams are unaffected
- The
-betasuffix onusecase-betais Mermaid's convention for a new diagram type whose syntax may still evolve (the same patharchitecture-betatook) — safe to use, syntax may gain features before it stabilizes
Where you get Mermaid 12
| App | Where the diagram lives | Try it |
|---|---|---|
| Enhanced Markdown for Confluence | Inline in any page, inside a ```mermaid fence, with live split preview | Free for up to 10 users |
| Mermaid Plus for Confluence | /mermaid macro with template picker and themes | Free for up to 10 users |
| Mermaid Plus Diagrams for Jira | Panel on every Jira issue — diagrams stay attached to the ticket | Free for up to 10 users |
One syntax, three homes: the same usecase-beta block renders in Confluence pages, Confluence macros, and Jira issues.
Common questions
Why use case diagrams in a wiki and a tracker? Because requirements live there. A use case diagram on the epic page or attached to the feature ticket gets seen in review; one exported from a UML tool gets stale in a drive nobody opens.
Can I combine this with the other Mermaid diagram types? Yes — a page can hold a use case diagram for scope, a flowchart for the happy path, and a sequence diagram for one interaction, all from text.
Is usecase-beta final syntax? It's beta by Mermaid's naming convention: feature-complete for actors, boundaries, include/extend, and notes, with syntax refinements possible before stabilization. Diagrams you build now may need small syntax touch-ups when it graduates — the usual trade for being early.
Related Resources
- Create Mermaid diagrams in Confluence — the step-by-step guide across all diagram families
- Mermaid diagrams on Jira issues — sequence, class, and settings for Jira panels
- All 29 Mermaid diagram types in Confluence — the complete reference, now with use case diagrams joining the family
- Mermaid syntax cheat sheet — quick reference for every diagram type
- Mermaid 12 release notes — the upstream changelog
Mermaid 12 turns a UML modeling tool's job into a one-minute paste. Open a page or issue, drop in the usecase-beta example above, and your requirements have a diagram that edits as fast as the text around it.
Try Mermaid Plus for Confluence
All 26 Mermaid diagram types with live preview and one-click templates — free for up to 10 users.
Get it on the Atlassian Marketplace