52 posts tagged with "mermaid"

Somewhere in your Confluence right now there are pages that depend on a third-party app to render. A diagram here, a markdown block there, a whiteboard embed somewhere else. The pages are fine. The app is fine. Everything is fine — until it isn't: the vendor retires the app, gets acquired, or your team outgrows it. And then a question almost nobody has asked out loud suddenly matters: what is actually stored on those pages, and what survives?

We just went through this cycle for Mermaid diagram apps — one major vendor just announced the end of life of its Connect-based app in January 2027 — and the experience taught us a lot about the real cost of macro migration. Not the license cost. The content cost. This post is that breakdown; the Mermaid story is the case study at the end.

The anatomy: what a macro actually leaves behind​

Confluence macros are stored inside the page itself. The app renders them live; Confluence only stores a small block describing the macro and its content. When the rendering app disappears, the page keeps the block but nothing draws it anymore. The text, the diagram definition, the table — whatever the app put in storage — is still there.

So content usually survives the app. What dies is the render. And that is the trap: "my pages still exist" feels safe until you open one and the diagram simply is not there anymore.

Whether the surviving data is usable depends entirely on the vendor:

• Some apps keep the human-readable source (Mermaid syntax, markdown) directly in storage
• Some wrap it in JSON with revision history
• Some store only a rendered image and keep the source in a proprietary attachment format
• Some do all three, depending on the app version that last touched the macro

Every one of those is a different migration project.

Why the cost is always higher than it looks​

Cost 1: the formats. Each vendor's storage format is undocumented and versioned. Reading "what's on the page" is not a query — it is a small reverse-engineering project per app, sometimes per app version. This is the single biggest line item in any macro migration.

Cost 2: the scale is invisible until you measure it. Teams consistently underestimate how many pages depend on an app, because diagrams are scattered — one here in an architecture doc, three there in a runbook. Nobody costs a migration they have not inventoried.

Cost 3: the app ecosystem keeps generating this problem. This is not a rare event. Atlassian ended its own Server product line in 2024, forcing one of the largest app-and-content migrations in the platform's history. Vendors retire or pivot — the Connect-based Mermaid app by Stratus reaches end of life in January 2027, the very case that prompted this post. Free first-party alternatives keep appearing in the same categories. And independent of any retirement, teams switch vendors — which is the same migration with a different trigger. If your team uses Confluence deeply today, the odds that it will face at least one macro migration in the next few years are close to certain.

Cost 4: the manual fallback is real but doesn't scale. Opening every page and recreating content by hand genuinely works — for ten pages. At a hundred, triage paralysis sets in: nobody costs it, nobody schedules it, and the migration quietly becomes "we'll deal with it when it breaks."

Case study: what migrating Mermaid diagrams took​

When the retirement news landed, we built migration support into our Mermaid app — and the economics matched the framework above almost exactly.

Inventory first. A scan reads page storage and counts macros per page. Teams that ran it found diagrams in spaces nobody expected — the invisible-scale problem, confirmed every time.

Four vendors, four formats. We ended up supporting four distinct storage layouts: source in a macro parameter, source in a JSON blob in the macro body, source in a companion code block, and a renderer macro that references all of the above. Four parsers, each a small reverse-engineering project against undocumented formats.

Conversion is text processing; judgment is not. Replacing an old macro with a new rendered diagram at the same position in the page is mechanical. The hard parts were elsewhere: pages that mix several vendors' macros (convert only what you scanned for?), diagrams whose source cannot be extracted (report them honestly, per page, or they vanish without a trace), and the rollback story (in-place conversion plus page history beats any backup script).

The result: a space sweep per source app, a review table before anything is written, and every conversion landing as a normal page version. That combination turned an unbounded, scary project into a bounded checklist.

The general checklist​

Whatever the macro type — diagrams, markdown, tables, whiteboards — the same checklist applies:

1. Inventory by scanning page storage, not by asking around
2. Map the formats: where each vendor keeps the source, and whether it is human-readable
3. Migrate one vendor at a time, with per-page results before anything is written
4. Convert in place and let page history be the rollback mechanism
5. Report failures per page — silent skips are how content quietly dies anyway

The teams that skip steps 1 and 2 are the teams whose migration "unexpectedly" takes a quarter.

If the macros you're leaving behind are Mermaid diagrams, you can start today: Mermaid Plus Diagrams & AI Agent for Confluence includes the migration wizard described above — it recognizes macros from Mermaid Chart, Stratus, the Atlassian Labs viewer, weweave and Tech Labs, and converts them in place. The migration guide walks through every step.

If you're switching away from a different macro type — draw.io, Excalidraw, markdown, tables — the checklist above still applies, and the same pipeline (inventory → parse → convert in place) is how we're expanding coverage: Excalidraw is next on the roadmap. Tell us which app you're switching from — the more we know about the formats teams are actually leaving, the faster that list grows.

And if you're mid-decision right now, bring it to the Community discussion — the "we'll migrate as we go" plan needs all the reality checks it can get.

Mermaid 12.2.0 shipped upstream on October 13, and it is live in all three NGPILOT diagram apps: Enhanced Markdown for Confluence, Mermaid Plus Diagrams & AI Agent for Confluence, and Mermaid Plus Diagrams for Jira. It's a small release with one feature you can see from across the room — mind maps that color themselves by hierarchy depth — and a set of quiet fixes that matter more on Confluence than anywhere else, because Confluence pages are where multiple diagrams share one page.

Confluence chat can write your page, summarize the thread, and answer questions about the space. What it couldn't do — until now — is draw. If you asked for "a flowchart of our deployment process," you got a text description of a flowchart, and someone still had to open an editor and build it.

The AI agent in Mermaid Plus Diagrams & AI Agent for Confluence closes that gap: it creates, reads, updates, and converts Mermaid diagrams directly on Confluence pages and blog posts, from chat.

Every Confluence team ends up choosing a diagram tool, and most start by asking the wrong question: does it support Mermaid? These days, two answers exist. Mermaid Plus Diagrams & AI Agent for Confluence is built around Mermaid — all 30 Mermaid v12 diagram types, a code editor with live preview, one-click templates for every type, and a Rovo AI agent that works on the page. draw.io is the most-installed diagramming app on the Atlassian Marketplace, with deep shape libraries, whiteboarding, and a Mermaid importer added to its editor.

Both are good tools. This guide compares how they behave in Confluence specifically — how a diagram is created, what is stored on the page, what happens when you need to change it six months later, and what it costs.

The diagrams live in the repository. They were written in Mermaid, they are reviewed in pull requests next to the code they describe, and they are correct as of the last commit. The documentation, however, lives in Confluence — because that is where the rest of the team reads it. So somebody copies a Markdown file across, pastes it into a Confluence page, and the flowcharts, sequence diagrams and ER models arrive as grey boxes of unrendered code.

Everyone has hit this. It is one of the most common Confluence complaints, and the usual workarounds are worse than the problem: export every diagram to PNG and re-upload them (now they rot), keep the diagrams in an external tool and paste links (readers need a second account, and the links break), or build a browser extension to force rendering on paste.

There is a better answer, and Mermaid 12 makes it better still.

The integration doc says "the client calls the API, the API validates and responds" — four words, zero contracts, and the onboarding engineer asks "with what headers, in what order, and what if auth fails?" The code has the truth; the wiki has a paragraph. An API that can't be read as a transcript is an API nobody can safely operate.

Quick answer: document API flows in Confluence as Mermaid — sequenceDiagram for request/response order, packet-beta for wire-format frames, ZenUML for branch-heavy async flows — rendered by Mermaid Plus Diagrams & AI Agent for Confluence. Each diagram type answers a different reader: what order, what's on the wire, what branches. This post gives you three copy-paste examples.

The onboarding doc says "check the architecture diagram" and the architecture diagram shows a monolith from 2023 that the team decommissioned in the spring. Nobody is lying — the draw.io file lives on one person's laptop, and the wiki holds a screenshot nobody owns. An architecture that only exists as a static export rots silently, because the thing you would edit is invisible to review.

Quick answer: document system architecture in Confluence as Mermaid text — C4Context for the system in context, architecture-beta for the deployment, block-beta for the topology you want laid out precisely — rendered by Mermaid Plus Diagrams & AI Agent for Confluence. Every level stays an editable code block, so the wiki's architecture changes in the same review that changes the system. This post gives you three copy-paste examples.

The quarterly review loads a 14-tab spreadsheet to answer one question — "where do we actually spend our engineering time?" — because the wiki charts are stale screenshots from last quarter and the numbers table nobody reads. A dashboard is not a spreadsheet: it is the two charts that answer the two questions people keep asking.

Quick answer: build dashboard charts in Confluence with Mermaid pie and xychart-beta charts, rendered by Mermaid Plus Diagrams & AI Agent for Confluence. Pie for shares, XY for trends — both as editable text that refreshes like code. This post gives you three copy-paste examples: an effort-share pie, a weekly trend XY, and a dual-series release dashboard.

A build fails at 4pm, and the fix's pipeline takes 40 minutes to re-run from the top because someone decided every stage needs to re-validate. That wasted hour is not a code problem — it is a documentation problem. Nobody could see the pipeline's shape, so nobody saw the retry loop and the gate that would have caught the failure three stages earlier.

Quick answer: put the pipeline's shape in Confluence as a Mermaid flowchart, rendered by Mermaid Plus Diagrams & AI Agent for Confluence. Text-based, editable, diffable — a pipeline diagram that changes when your pipeline changes. This post gives you three copy-paste examples: the linear stage view, quality gates with retry loops, and the deploy-to-tag gitGraph that records what actually shipped.

Your team grows by two people. The new hires open the wiki and find the architecture doc: a screenshot of a whiteboard, dated 14 months ago, where PaymentService does everything except the thing the diagram says OrderService does. Day-1 onboarding just taught two people the wrong architecture.

Quick answer: keep the architecture in Confluence as a Mermaid class diagram, rendered by Mermaid Plus Diagrams & AI Agent for Confluence and diffs like code. Classes, methods, interfaces, ownership — in editable text that updates when the code does. This post gives you three copy-paste examples: the onboarding service map, interface+implementation modules, and a request-flow sketch.

The meeting asks "who owns this feature?" and the answer is a Venn diagram by hand — drawn on a whiteboard, erased, redrawn, photographed, and lost. Two teams each built a piece of a shared workflow, and "the overlap" is exactly where the bugs and the SQL both landed. A decision framework is only useful while its picture survives the meeting; in Confluence as Mermaid text, it survives.

Quick answer: put decision frameworks in Confluence as Mermaid — venn-beta for set overlap, cynefin-beta for which operating mode a situation needs, quadrantChart for which item goes first — rendered by Mermaid Plus Diagrams & AI Agent for Confluence. Each framework encodes a decision shape, and text keeps the picture attached to the decision record. This post gives you three copy-paste examples.

The bug report says "orders show twice in the report" and the fix takes three days because nobody on the team is sure whether order_lines links to orders on order_id or source_order_id, and both columns exist. The schema is documented — in a schema.md that lists columns as bullets and a diagram that was last exported when the DB was two migrations younger. The join question is exactly the thing an ER diagram answers at a glance, and the thing a bulleted column list cannot answer at all.

Quick answer: document the database schema in Confluence as a Mermaid erDiagram, rendered by Mermaid Plus Diagrams & AI Agent for Confluence. Entities hold keys and attributes; relationship lines carry the cardinality and the join's noun. When the discussion turns to the domain model the code exposes, add a classDiagram on the same page. This post gives you three copy-paste examples.

A root cause analysis is only as good as the disagreement it survives. When the 'root cause' box on your postmortem template contains one sentence, the meeting spends an hour relitigating that sentence. A fishbone diagram and a 5 Whys chain move the argument onto a diagram: everyone sees which categories were considered, which branch was chosen, and exactly how the 'why' answers arrive at a root cause.

Confluence is where RCA already happens — in the Root Cause Analysis template, in postmortems, in retros. The missing piece is a diagram that holds the reasoning. This guide shows you two copy-paste Mermaid diagrams: an ishikawa fishbone that maps every candidate cause category, and a flowchart 5-Whys drilldown that lands on one concrete fix.

Your team is mid-debug on a prod incident. A senior engineer asks "which release shipped this commit, and why is it on the release branch when the PR said main?" — and nobody can answer without switching between Jira, the git web UI, and a Slack thread. That context — commit history, branches, merge points, release versions — belongs next to the issue, not in a tool people have to leave Jira to open.

Quick answer: paste a Mermaid gitGraph into the issue's Mermaid Plus Diagrams for Jira panel and the branch history renders as a diagram right on the ticket — commits, branches, merges, and release tags, all in one editable text block. This post gives you three copy-paste examples: a trunk-based feature workflow, a hotfix outside the release window, and a branch-rule flowchart to keep behavior consistent.

Every incident has a story hidden inside a pile of timestamps: alert fired at 09:42, nobody acknowledged until 09:47, an engineer escalated at 09:54, a workaround landed at 10:20, services healthy at 10:31. Individually the timestamps mean nothing. Laid out on a timeline, they tell the story — and the story is what a postmortem is for.

Confluence is where incident postmortems already live. What Confluence does not give you is a native timeline. This guide shows you how to fill the Timeline section of an incident postmortem with a Mermaid diagram: one copy-paste timeline that visualizes detection → escalation → resolution, plus a sequence diagram that shows exactly how the failure propagated between services.

The support team knows where refunds leak. The product team knows where onboarding drops. The sales team knows where the pricing page confuses. Three silos, three versions of the customer's experience — and the roadmap meeting spends an hour reconciling them instead of deciding what to fix. What is missing is a single picture with a score on every step.

Quick answer: draw customer journeys in Confluence as Mermaid journey diagrams, rendered by Mermaid Plus Diagrams & AI Agent for Confluence. A journey diagram puts every step in a row and every satisfaction score on one curve — the dips are visible, the actors are labeled, and the whole thing stays editable text. This post gives you three copy-paste examples: onboarding, a support ticket, and a checkout flow with a summary pie.

The sprint board on the wall shows 40 items in "In Progress" and the rulebook says "we limit WIP" and nobody agrees on what the limit is. The board is honest; the documentation is aspirational. A Kanban diagram in the wiki is the board as a spec — columns, limits, and the rework paths drawn so the workflow is a claim the team can argue with.

Quick answer: document the team's board in Confluence as a Mermaid kanban, rendered by Mermaid Plus Diagrams & AI Agent for Confluence. Columns as headings, work items as indented cards; the workflow rules (who may move what, when, including rework) as a stateDiagram on the same page. This post gives you three copy-paste examples.

The kickoff note is 40 lines of indented bullets with three levels of bolded sub-points, and half the room is still asking "so what are we actually deciding today?" The other half is screenshotting a mind map someone whiteboarded in five minutes. The whiteboard died at cleanup; the bullets survived but nobody can navigate them. A mind map is the readable version of nested notes — and when it lives in Confluence as Mermaid text, it survives the meeting.

Quick answer: turn nested notes into a Mermaid mindmap in Confluence, rendered by Mermaid Plus Diagrams & AI Agent for Confluence. The indented text you already write becomes the branches; for concrete structures — folder layouts, project trees — use treeView; when item size matters and you want area instead of lines, use treemap. This post gives you three copy-paste examples.

The ticket sits in "Waiting on customer" for a week and nobody noticed, because the handoff between first-line support and the dev team is a tacit step: Support marks it "escalated" in one field, Engineering is supposed to watch a filter, and the transfer never surfaces as its own action. That inert weekend is a process bug, and the fix is to see the handoff. A swimlane diagram makes the ownership transfer its own crossing arrow — invisible to everyone until it is drawn.

Quick answer: map cross-functional processes in Confluence as Mermaid swimlane-beta, rendered by Mermaid Plus Diagrams & AI Agent for Confluence. One lane per actor, steps sequenced inside lanes, and the handoff is the arrow that crosses a lane boundary. When the interaction is a short request/response instead of long-running work, switch to a sequenceDiagram. This post gives you three copy-paste examples.

The team page says "we own the checkout" and the skills tab lists four words nobody updated. When the sprint needs a React engineer, the wiki can't say who is nearest. Meanwhile, the contributor guide links to a repo whose shape is a mystery ship in a fog of folders. Structure and capability both want drawing — and both draw from plain text.

Quick answer: track capabilities and structure in Confluence as Mermaid — radar-beta for multi-axis comparison across profiles, treeView-beta for repo and structure maps, railroad-ebnf-beta for syntax and grammar diagrams — rendered by Mermaid Plus Diagrams & AI Agent for Confluence. Each chart answers a different "what's the shape": of the team, of the repo, of the language. This post gives you three copy-paste examples.

The feature ships with a test suite that validates four scenarios. The PRD lists seven requirements. The compliance review asks "which requirement is the encryption actually in scope for?" — and the answer is a spreadsheet cross-referenced by color, maintained by one person, last updated before the sprint began. Traceability does not scale as a spreadsheet; it scales as a diagram that is the trace.

Quick answer: document requirements traceability in Confluence as Mermaid requirementDiagram, rendered by Mermaid Plus Diagrams & AI Agent for Confluence. Each requirement connects to the elements that satisfy and verify it — the gaps read at a glance, and the whole thing stays editable text next to the PRD. This post gives you three copy-paste examples: a feature trace, a compliance control, and an epic-to-test gap review.

The quarter plan is a spreadsheet with thirty rows, color-coded by priority, sorted by a column half the team doesn't trust. The kickoff asks "what are we doing when — and why this first?" and the answer requires parsing three tabs. Planning outputs are shapes: schedules stack as bars, priorities sit on a 2x2, flows bundle as ribbons. The spreadsheet stores them poorly; Mermaid draws them as text.

Quick answer: put the quarter plan in Confluence as Mermaid — gantt for when things happen, quadrantChart for which gets built first, sankey-beta for where the budget goes — rendered by Mermaid Plus Diagrams & AI Agent for Confluence. Three charts, three planning questions, one editable page. This post gives you three copy-paste examples.

The issue workflow lives in a wiki page that says "the approval chain is: team lead, then manager, then finance". The config says otherwise, the Jira post-function disagrees, and the incident report asks "who actually approved this?" — with three different answers on screen. A prose paragraph cannot hold a workflow; a diagram can, if it is the workflow.

Quick answer: document state machines and approval chains in Confluence as Mermaid stateDiagram-v2, rendered by Mermaid Plus Diagrams & AI Agent for Confluence. Every legal state, every transition, every human decision on a labeled arrow — in editable text that stays true. This post gives you three copy-paste examples: an issue lifecycle, a spending approval chain, and a retry loop with a timeout.

The use case diagram is the scope picture: actors on the outside, what the system does for them on the inside, and — the reason product and engineering fight — the line between them. In Confluence that picture usually comes from a diagramming tool export that goes stale the moment scope moves.

Mermaid 12 added the syntax to render UML use case diagrams from text — usecase-beta — and Enhanced Markdown for Confluence renders it in the same macro as everything else on the page. This guide gives you the syntax and two copy-paste diagrams.

Sequence diagrams die in Confluence in one of two ways: someone draws one in a diagramming tool, exports a PNG, pastes it into a page — and three sprints later the flow has changed but the image has not. Or someone writes the flow as prose ("the client calls the order service, and if payment is approved…"), which is accurate but impossible to read under time pressure.

ZenUML splits the difference: the diagram is code, so it edits like code and renders like a diagram — branches, error paths, and parallel work included. This guide shows the syntax with copy-paste examples you can drop into Confluence today.

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 Diagrams & AI Agent 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.

Jira is where the work happens — but the process behind the work usually lives in someone's head or in a stale Confluence page nobody opens. A flowchart on the Jira issue itself fixes that: bug triage paths, approval chains, and escalation procedures become visual, unambiguous, and impossible to miss.

Jira Cloud gives you two ways to get there, and they serve different needs. This guide walks through both, then gives you three copy-paste Mermaid flowchart examples for the scenarios Jira teams hit most: bug triage, approval workflows, and incident escalation.

A release date doesn't slip in one dramatic moment — it slips in six quiet ones: QA took two extra days, staging froze late, sign-off waited on legal. A release timeline pinned to the release epic makes those slips visible while they're still cheap to fix, because every stakeholder reads the same picture of what's next and what's blocked.

Jira gives you three ways to build that picture. This guide walks through them, then gives three copy-paste Mermaid Gantt examples sized for real releases: a single version, a multi-team launch, and a launch-week sequence.

Text-based diagramming — writing a few lines of code that render into a diagram — is how modern teams keep diagrams in sync with their documentation. No more drawing boxes by hand in Visio, exporting screenshots, and pasting them into Confluence where they go stale. With text-based diagrams, you edit the source and the diagram redraws instantly.

But there are three major text-based diagramming languages, and they are not interchangeable. Each has different strengths, different syntax, and different ideal use cases. This guide compares Mermaid, PlantUML, and Graphviz so you can choose the right one (or combination) for your Confluence team.

Every team that adopts Jira diagrams hits the same moment: you discover Mermaid supports 30 diagram types, you get excited, and then you realize you have no idea which ones to actually use during a sprint. Most of them never get drawn. The diagrams that earn their keep are the ones that make a standup faster, an onboarding doc clearer, or a ticket unambiguous — and those are a small, repeatable subset.

This post is the workflow guide we wish we'd had: the four diagram types a sprint team actually uses, each with a real scenario and copy-paste syntax you can drop straight into a Jira issue. The full 30-type reference follows, so the same page works as both a sprint playbook and a complete catalog.

The scenario every technical team hits: your engineering docs live in Markdown — READMEs, API references, design docs — and they contain diagrams (Mermaid), equations (LaTeX), and code samples. You paste that Markdown into Confluence, and it falls apart. The Mermaid code blocks render as plain text. The LaTeX equations show as raw $...$ syntax. The code blocks lose their syntax highlighting. Confluence's native editor is WYSIWYG, not Markdown, and the import tools treat Markdown as a one-time conversion rather than something you edit live.

Enhanced Markdown for Confluence solves this with a Markdown editor that renders everything inline — Mermaid diagrams, KaTeX and LaTeX math, syntax-highlighted code, and GitHub-flavored tables — with a live split preview. It runs on the Quikdown engine, so all rendering libraries are bundled locally (no external CDN dependencies, which matters for "Runs on Atlassian" compliance). This guide walks through writing Markdown in Confluence with diagrams, math, and code all rendering live.

Need diagram tools for Confluence without paying for a large team? NGPILOT's three diagramming apps — Mermaid Plus, Excalidraw Plus, and Graphviz Charts — are all free for up to 10 users. This guide compares them so you can pick the right free diagram plugin for your Confluence.

Adding diagrams to Confluence pages helps teams communicate architecture, processes, and workflows visually. This guide covers the three main approaches to creating diagrams in Confluence and helps you choose the right tool for your needs.

No, Confluence does not support Mermaid diagrams natively. There is no built-in macro or feature that renders Mermaid syntax in Confluence pages. To add Mermaid diagrams to Confluence, you need a Marketplace app.

This guide covers how to set up Mermaid in Confluence and which diagram types you can create.

Sequence diagrams are one of the most widely used diagram types in software documentation. They show exactly how participants -- users, services, databases, external APIs -- exchange messages over time. For Confluence teams, embedding sequence diagrams directly on wiki pages means architecture docs, API specifications, and incident post-mortems stay in one place instead of scattered across external tools.

Mermaid's text-based syntax makes sequence diagrams fast to write and easy to update, but the syntax has its own set of rules that can trip you up. This FAQ answers the questions Confluence users ask most often about building sequence diagrams with Mermaid, with expanded explanations, working code examples, and copy-paste templates you can drop straight into a Mermaid Plus macro.

Mermaid supports 30 diagram types — from flowcharts and sequence diagrams to C4 architecture, swimlanes, Gantt charts, ER diagrams, git graphs, and more. With Mermaid Plus Diagrams & AI Agent for Confluence, all 30 render from plain text inside a single macro. This page is the complete reference: every type, its keyword, its category, when to use it, and worked examples for the ones a software team reaches for most.

If you are deciding which diagram type fits your use case, jump to When to use each Mermaid diagram type. For the quick reference table, see below. For installation and the macro basics, see Create Mermaid diagrams in Confluence.

Mermaid is the most popular text-based diagramming language for technical documentation. One line of code generates a flowchart. A few more produce a sequence diagram, ER diagram, or Gantt chart. Teams using Confluence can embed Mermaid diagrams directly on their pages, keeping diagrams alongside the documentation they illustrate.

Architecture diagrams are the backbone of technical documentation. They show how services communicate, where data flows, and which infrastructure components underpin your system. When a new engineer joins your team, the first thing they look for is an architecture diagram. When something breaks in production, the incident response starts at the same diagram.

Yet many teams store their architecture diagrams in external tools -- draw.io, Lucidchart, or even desktop applications -- detached from the documentation where they matter most. Confluence is where your runbooks live, where architecture decision records are written, and where post-mortem discussions happen. Keeping your architecture diagrams inside Confluence eliminates context-switching and ensures diagrams evolve alongside the written documentation they illustrate.

This guide walks through three ways to create architecture diagrams directly in Confluence, using NGPILOT apps designed for different workflows. Every Mermaid example is copy-paste ready, so you can insert it into a Confluence page and see the result immediately.

Class diagrams are the standard way to model object-oriented systems. They show the classes in your codebase, their attributes and methods, and the relationships between them -- inheritance hierarchies, composition, aggregation, and simple associations. Whether you are documenting a domain model, onboarding new engineers onto a codebase, or collaborating on a design before writing a single line of code, a UML class diagram communicates structure faster than paragraphs of prose.

If your team uses Confluence for technical documentation, embedding class diagrams directly on your pages keeps your design docs next to your architecture decisions, runbooks, and sprint planning notes. With Mermaid Plus Diagrams & AI Agent for Confluence, you can write class diagrams in plain text and render them instantly, no external drawing tool required.

An ER diagram (entity-relationship diagram) visualizes a database schema — the tables, columns, primary and foreign keys, and the relationships between them. If your team documents data models, API contracts, or system architecture in Confluence, embedding ER diagrams directly on the page keeps the schema next to the prose instead of stranded in an external tool as a stale screenshot.

Confluence has no built-in ER diagram support, so you add it with a Marketplace app. The approach below uses Mermaid Plus Diagrams & AI Agent for Confluence, which renders ER diagrams from plain text — meaning diagrams version, diff, and search alongside the rest of your documentation.

Entity-Relationship (ER) diagrams are the standard way to visualize database schemas. They show the tables in your database, the columns in each table, primary and foreign key constraints, and the relationships between tables -- one-to-one, one-to-many, and many-to-many. Whether you are designing a new database from scratch, documenting an existing schema for onboarding, or collaborating on a data model before writing migration scripts, an ER diagram communicates structure faster than any amount of prose.

Gantt charts are one of the most widely used visual tools in project management. They give teams a clear, time-based view of who is doing what, when tasks start and end, and how dependencies chain together across a project lifecycle. Whether you are planning a software release, coordinating a marketing campaign, or managing a sprint backlog, a Gantt chart turns a flat task list into a timeline your whole team can read at a glance.

Confluence is where many teams already store their project documentation, meeting notes, and decision records. Embedding Gantt charts directly on Confluence pages keeps your project visuals alongside the context your team needs, instead of burying timelines in a separate project management tool that nobody checks. With Mermaid Plus Diagrams & AI Agent for Confluence, you can write Gantt charts using plain text syntax and see them rendered instantly on the page.

Jira issues are where your team tracks bugs, features, and tasks every day. But describing complex processes, API interactions, or system designs in plain text often leads to confusion and misalignment. Mermaid Plus Diagrams for Jira solves this by letting you create and embed Mermaid diagrams directly on any Jira issue, so the visual context lives exactly where the work happens. No external tools, no attached images that go stale, no switching between tabs.

Mind maps are one of the most effective ways to capture ideas, organize thoughts, and brainstorm with a team. Unlike linear notes or bullet lists, mind maps radiate outward from a central topic, making it easy to see relationships between concepts at a glance. If your team already uses Confluence for documentation, meeting notes, and project planning, adding mind maps directly to your Confluence pages keeps brainstorming sessions alongside the rest of your team's knowledge.

In this tutorial, you will learn how to create mind maps in Confluence using Mermaid syntax and the Mermaid Plus Diagrams & AI Agent for Confluence app. Every example is copy-paste ready, so you can drop it straight into a Confluence page and start organizing your ideas immediately.

Pie charts are one of the simplest and most effective ways to communicate proportional data. Whether you are reporting survey results, breaking down a project budget, or showing how your team allocates time across activities, a pie chart turns a list of numbers into a visual that anyone can read in seconds. Confluence is where your team already stores reports, retrospectives, and planning documents, so embedding pie charts directly on those pages keeps your data alongside the context that explains it.

With Mermaid Plus Diagrams & AI Agent for Confluence, you can create pie charts and other data visualizations using plain text syntax. No image exports, no spreadsheet screenshots, no broken attachments. You write the code once, and the chart renders directly on the Confluence page, updating whenever you edit the underlying data.

Sequence diagrams are one of the most practical tools in a software team's documentation toolkit. They show how objects, services, or actors interact over time, making them ideal for documenting API flows, authentication processes, microservice choreography, and error-handling logic. If your team uses Confluence for documentation, embedding sequence diagrams directly on your pages keeps architecture docs alongside everything else your team needs.

In this tutorial, you will learn how to create sequence diagrams in Confluence using Mermaid syntax. Every example is copy-paste ready, so you can drop it straight into a Confluence page and see the result immediately. The examples use Mermaid Plus Diagrams & AI Agent for Confluence, which renders the full Mermaid v12 syntax natively in Confluence Cloud — free to try from the Marketplace.

State diagrams (also called state machine diagrams) model how a system transitions between discrete states in response to events. They are essential for documenting order lifecycles, user authentication flows, CI/CD pipelines, IoT device behavior, and any system where the current state determines what happens next. If your team uses Confluence for technical documentation, embedding state diagrams directly on your pages keeps your design decisions alongside runbooks, architecture decision records, and sprint planning notes.

In this tutorial, you will learn how to create state diagrams in Confluence using the Mermaid stateDiagram-v2 syntax. Every example is copy-paste ready, so you can drop it straight into a Confluence page and see the rendered result immediately.

Looking for the best diagram tool for Confluence? Confluence has no built-in diagramming, so every team adds a Marketplace app — but the right choice depends entirely on what you draw and how you prefer to work. This guide compares the three strongest options — Mermaid Plus Diagrams & AI Agent for Confluence, Excalidraw Plus Whiteboards & AI Agent for Confluence, and Graphviz Charts for Confluence — so you can pick the diagram tool that fits your team instead of guessing.

Flowcharts are one of the most common diagrams teams add to Confluence pages — for process documentation, onboarding, decision trees, and troubleshooting guides. This article shows three ways to create them using NGPILOT apps.

Mermaid diagrams in Confluence let you create flowcharts, sequence diagrams, and more using simple text syntax. This guide covers Confluence Mermaid setup with Mermaid Plus — live preview, 30 diagram types, and copy-paste examples.

Every engineering team needs diagrams in Jira — architecture decisions on epics, bug reproduction flows on tickets, wireframes on stories. But Jira has no built-in diagramming. You either paste screenshots from external tools or install a marketplace app.

We built two diagram apps for Jira: Mermaid+ Diagrams for Jira for text-based diagrams using Mermaid syntax (flowcharts, sequence diagrams, ER models, C4 architecture), and Excalidraw Diagrams + Whiteboards for Jira for freeform drawing with 229 built-in shape libraries. In this post we compare both against every alternative on the Atlassian Marketplace.

Engineering teams need diagrams in Confluence — flowcharts for runbooks, sequence diagrams for API docs, ER models for database schemas, architecture diagrams for design decisions. Writing diagrams as code (text-based syntax) is faster than drag-and-drop for developers. Mermaid is the most popular text-based diagram language.

Several marketplace apps bring Mermaid to Confluence, plus the major visual diagramming tools (draw.io, Gliffy, Lucidchart) also support it. We built Mermaid Plus Diagrams & AI Agent for Confluence to offer 30 diagram types with live preview, one-click templates, and a built-in syntax guide. In this post we compare it against every alternative.