Which Mermaid Diagram Types Work Best for Software Documentation in Confluence?
Mermaid gives Confluence teams access to 26 diagram types, all rendered from plain text inside a single macro. That breadth of choice is a strength, but it also raises a practical question: which diagram types should your team actually use, and when? Picking the wrong type makes documentation harder to read, not easier. This FAQ walks through every Mermaid diagram type, explains which ones matter most for software documentation, and helps you make the right call for each scenario.
Whether you are documenting a microservices architecture, onboarding new engineers, or writing an RFC, the diagrams you choose shape how quickly your audience can understand the system. Flowcharts, sequence diagrams, and ER diagrams are the workhorses of most teams, but Mermaid also offers specialized types like C4 diagrams, git graphs, and kanban boards that solve specific documentation problems. This guide covers all of them, with a comparison table and practical advice for using each type inside Confluence.
All 26 Mermaid Diagram Types at a Glance
Mermaid supports the following diagram types. Each one has a dedicated keyword that you use at the top of your code block to tell the renderer which type to expect.
| # | Diagram Type | Keyword | Category |
|---|---|---|---|
| 1 | Flowchart | flowchart or graph | Process |
| 2 | Sequence Diagram | sequenceDiagram | Interaction |
| 3 | Class Diagram | classDiagram | Structure |
| 4 | State Diagram | stateDiagram-v2 | Behavior |
| 5 | ER Diagram | erDiagram | Data |
| 6 | User Journey | journey | UX |
| 7 | Gantt Chart | gantt | Planning |
| 8 | Pie Chart | pie | Data |
| 9 | Git Graph | gitGraph | Version Control |
| 10 | Mindmap | mindmap | Brainstorming |
| 11 | Timeline | timeline | Chronology |
| 12 | Requirement Diagram | requirementDiagram | Requirements |
| 13 | C4 Diagram | C4Context / C4Container / C4Deployment | Architecture |
| 14 | Quadrant Chart | quadrantChart | Analysis |
| 15 | Sankey Diagram | sankey-beta | Flow |
| 16 | XY Chart | xychart-beta | Data |
| 17 | Block Diagram | block-beta | Structure |
| 18 | Packet Diagram | packet-beta | Networking |
| 19 | Kanban Board | kanban | Workflow |
| 20 | Architecture Diagram | architecture-beta | Infrastructure |
| 21 | Radar Chart | radar-beta | Comparison |
| 22 | TreeView | treeView-beta | Hierarchy |
| 23 | Treemap | treemap | Data |
| 24 | Ishikawa (Fishbone) | ishikawa | Root Cause |
| 25 | Venn Diagram | venn-beta | Sets |
| 26 | ZenUML | zenuml | Interaction |
All 26 types are supported in Mermaid Plus for Confluence. You can access one-click templates for each type from the Quick Templates panel in the macro configuration.
Frequently Asked Questions
1. How many Mermaid diagram types are there, and which ones does Confluence support?
Mermaid currently supports 26 diagram types, ranging from flowcharts and sequence diagrams to radar charts and fishbone diagrams. Mermaid Plus for Confluence supports all 26 types through a single macro -- type /mermaid in the editor, choose your diagram from the Quick Templates panel, and start writing. Every diagram type is available with live preview, so you can see changes in real time as you write.
The 26 types span several broad categories. Process diagrams (flowcharts, kanban) capture workflows and decision logic. Interaction diagrams (sequence, ZenUML) show how components communicate over time. Structure diagrams (class, ER, block) model data and code organization. Planning diagrams (Gantt, timeline) visualize schedules. Data diagrams (pie, XY chart, treemap) present quantitative information. Specialized types like C4, git graph, and packet diagram address domain-specific needs such as architecture documentation, branching strategy visualization, and network protocol illustration.
For a complete syntax reference with code examples for every diagram type, see the Mermaid Plus for Confluence usage guide.
2. Which Mermaid diagram types are most useful for software development teams?
The five most essential diagram types for software teams are flowcharts (process and decision logic), sequence diagrams (service interactions and API flows), class diagrams (object-oriented design), ER diagrams (database schemas), and state diagrams (lifecycle and status transitions). C4 diagrams are also highly valuable for architecture documentation. These six types cover the majority of documentation needs in a typical engineering organization.
Flowcharts are the most versatile. Use them for CI/CD pipeline visualization, user journey mapping, decision trees, and any process with branching logic. The flowchart keyword supports four directions (TD, LR, BT, RL) and rich node shapes including diamonds for decisions, cylinders for databases, and circles for connectors.
flowchart LR
A[Code Push] --> B[CI Build]
B --> C{Tests Pass?}
C -->|Yes| D[Deploy to Staging]
C -->|No| E[Notify Team]
D --> F{QA Approved?}
F -->|Yes| G[Deploy to Production]
F -->|No| H[Rollback]
Sequence diagrams are indispensable for documenting API interactions, service-to-service communication, and any protocol where order matters. They show participants as vertical lifelines with horizontal arrows representing messages. For detailed guidance, see our guide to creating sequence diagrams in Confluence.
Class diagrams capture object-oriented design, showing classes with their attributes, methods, and relationships (inheritance, composition, aggregation). They are essential for design documents and API documentation. See our class diagram tutorial for Confluence for a deeper walkthrough.
ER diagrams document database schemas and entity relationships using a compact notation (||--o{ for one-to-many, ||--|| for one-to-one). They are the fastest way to communicate a data model in a design doc or migration plan.
State diagrams model the lifecycle of entities -- order statuses, user account states, deployment phases, and similar state machines that drive business logic.
C4 diagrams follow the C4 model for software architecture, letting you document systems at context, container, and deployment levels. They are the right choice when you need to show how services, databases, and external systems relate to each other.
3. Do all Mermaid diagram types render correctly in Confluence?
Yes, all 26 diagram types render correctly when using Mermaid Plus for Confluence. The app pre-renders diagrams to cached SVG at save time, so pages load fast and diagrams display consistently for all viewers. Beta diagram types like sankey-beta, xychart-beta, and block-beta are fully supported. The only consideration is that very large diagrams (over 100 nodes) may benefit from being split into smaller pieces for better readability.
Rendering reliability depends on a few factors. First, ensure you are using the correct keyword for each diagram type. A misspelled keyword (for example, flowshart instead of flowchart) will cause the renderer to fail silently or display raw code. Second, verify that special characters in labels are wrapped in double quotes -- labels containing parentheses, brackets, or angle brackets must be quoted to parse correctly. Third, keep your diagram complexity reasonable. While Mermaid can handle hundreds of nodes, layouts become harder to read as diagrams grow.
The live preview in Mermaid Plus makes it easy to catch rendering issues before you save. As you type, the left column of the configuration panel updates in real time. If your code has a syntax error, the preview shows the error message immediately, so you can fix it before inserting the macro into the page.
For comprehensive troubleshooting guidance, see our Mermaid syntax cheat sheet for Confluence.
4. How do I choose the right Mermaid diagram type for my documentation?
Match the diagram type to the story you are telling. Use flowcharts for processes and decisions, sequence diagrams for interactions over time, class diagrams for code structure, ER diagrams for data relationships, state diagrams for status changes, Gantt charts for timelines, C4 diagrams for architecture, and mindmaps for brainstorming. If you are unsure, start with a flowchart -- it is the most versatile type and works well for most software documentation scenarios.
Here is a decision framework based on the question you are trying to answer:
"How does this process work?" -- Use a flowchart. Flowcharts handle branching logic, parallel paths, and decision points naturally. They are the default choice for documenting any multi-step process.
"How do these systems talk to each other?" -- Use a sequence diagram. When the order of messages matters and you need to show who sends what to whom, sequence diagrams are the clearest representation.
"What does the data model look like?" -- Use an ER diagram for database schemas and relational data, or a class diagram for object models with behavior.
"What states can this entity be in?" -- Use a state diagram. State diagrams are ideal for order lifecycles, approval workflows, and any system with defined transitions between discrete states.
"What is the architecture?" -- Use a C4 diagram for formal C4 model documentation, or an architecture diagram (architecture-beta) for infrastructure and service topology. Flowcharts also work well for simplified architecture views.
"What is the timeline?" -- Use a Gantt chart for project schedules with dependencies, or a timeline for chronological events without dependency tracking.
"How is this built in code?" -- Use a class diagram for OOP class hierarchies, a block diagram for component layout, or a TreeView for file and directory structure.
"What went wrong?" -- Use an Ishikawa (fishbone) diagram for root cause analysis, or a quadrant chart for prioritizing factors by urgency and impact.
5. Can I use multiple Mermaid diagram types on the same Confluence page?
Absolutely. You can insert as many Mermaid macros as you need on a single page, and each one can use a different diagram type. This is especially useful for architecture decision records, design documents, and onboarding guides where you need a flowchart for the process, a sequence diagram for the API flow, and an ER diagram for the data model all in one place. For performance, try to keep the total node count across all diagrams reasonable -- under 200 nodes per page is a good guideline.
Combining multiple diagram types on a single page is one of the most effective documentation patterns. A well-structured design document might include:
- A flowchart showing the high-level process at the top of the page
- A sequence diagram detailing the API interaction for a specific step
- A class diagram or ER diagram documenting the data model
- A state diagram showing entity lifecycle transitions
This layered approach lets readers understand the system at different levels of abstraction. Someone who just needs the big picture can read the flowchart and skip the details, while an engineer implementing a specific service can dive into the sequence diagram and class diagram for that component.
To keep pages performant, Mermaid Plus pre-renders each diagram to a cached SVG at save time. This means the page does not execute JavaScript for every diagram on load -- it simply displays the pre-rendered images. Even pages with five or six diagrams load quickly because the rendering work was done once when the author saved the page.
6. What are the beta Mermaid diagram types, and are they stable enough for production documentation?
Mermaid marks newer diagram types with a -beta suffix during their initial release phase. These include block-beta, packet-beta, architecture-beta, radar-beta, treeView-beta, venn-beta, and sankey-beta. Despite the beta label, these diagram types are stable enough for production use in Confluence and render reliably through Mermaid Plus. The suffix simply means the syntax may receive minor refinements in future Mermaid versions, so your diagrams may need small adjustments after upgrading.
The beta types are some of the most useful additions to Mermaid in recent versions. Here is what each one offers:
block-beta-- Component block diagrams with columns and nested groups. Useful for system-level architecture views where you need more control over layout than a flowchart provides.packet-beta-- Network packet structure diagrams that show field positions and bit ranges. Essential for protocol documentation and network engineering.architecture-beta-- Infrastructure and service architecture diagrams with cloud, database, and server icons. A lighter-weight alternative to C4 diagrams.radar-beta-- Multi-axis comparison charts. Useful for technology evaluations, skill assessments, and feature comparisons.treeView-beta-- File and folder tree visualizations. Great for documenting project structure, configuration hierarchies, and directory layouts.venn-beta-- Set relationship diagrams showing overlaps between categories. Useful for stakeholder analysis and capability mapping.sankey-beta-- Flow diagrams that show quantities moving through a system. Ideal for data pipeline visualization and resource allocation charts.
All of these render correctly in Mermaid Plus for Confluence. When you open the Quick Templates panel, each beta type has its own template with working code that you can modify.
Comparison: Top 10 Mermaid Diagram Types for Software Teams
The table below compares the ten diagram types most commonly used in software documentation, with guidance on when each one is the right choice.
| Diagram Type | Keyword | Best For | Confluence Rendering | Complexity |
|---|---|---|---|---|
| Flowchart | flowchart | Process flows, decision trees, CI/CD pipelines, onboarding steps | Full support with all directions and node shapes | Low to Medium |
| Sequence | sequenceDiagram | API call flows, service interactions, protocol documentation | Full support with notes, loops, and alt blocks | Low to Medium |
| Class | classDiagram | OOP design, API data models, interface contracts | Full support with visibility, inheritance, composition | Medium |
| ER | erDiagram | Database schemas, data models, migration planning | Full support with all relationship notations | Low |
| State | stateDiagram-v2 | Entity lifecycles, order statuses, deployment states | Full support with composite states and notes | Medium |
| C4 | C4Context | System architecture, service boundaries, deployment topology | Full support with context, container, and deployment views | Medium to High |
| Gantt | gantt | Sprint planning, release timelines, project milestones | Full support with dependencies and task states | Low |
| Git Graph | gitGraph | Branching strategies, release workflows, Git collaboration | Full support with merge, branch, and commit | Low |
| Mindmap | mindmap | Brainstorming sessions, topic breakdowns, knowledge maps | Full support with multi-level branching | Low |
| Architecture | architecture-beta | Infrastructure topology, service dependencies, cloud diagrams | Full support with typed service icons | Medium |
When to Use Each Mermaid Diagram Type
Flowcharts: The Default Choice
Flowcharts are the most commonly used Mermaid diagram type for good reason. They handle any scenario where you need to show steps, decisions, and branches. For software teams, the most frequent use cases are CI/CD pipeline documentation, user onboarding flows, error handling paths, and high-level system overviews.
Use a flowchart when your diagram has decision points (diamond nodes), parallel paths, or loops. Choose the direction based on the shape of your content: top-down (TD) for hierarchical processes, left-right (LR) for linear pipelines.
Sequence Diagrams: API and Service Communication
Sequence diagrams shine when you need to show who talks to whom and in what order. They are the standard choice for documenting REST API interactions, gRPC call chains, event-driven architectures, and any multi-service workflow where timing matters.
Each participant gets a vertical lifeline, and horizontal arrows represent messages. Solid arrows indicate synchronous calls, dashed arrows indicate responses, and open-arrow heads indicate asynchronous messages. You can add notes, loop blocks, and alternative (alt) blocks for conditional flows.
Class Diagrams: Code and Data Structure
Class diagrams are essential for object-oriented design documentation. They show classes with their attributes and methods, along with relationships like inheritance (<|--), composition (*--), aggregation (o--), and dependency (..>). Use them in design documents, API specifications, and onboarding materials where new engineers need to understand the codebase structure quickly.
ER Diagrams: Database Documentation
ER diagrams are the fastest way to document a database schema in text. They use a compact notation for relationships that is both human-readable and precise. Use them in migration plans, data model reviews, and any documentation that needs to explain how entities relate to each other.
State Diagrams: Lifecycle and Status Documentation
State diagrams model the transitions an entity goes through during its lifetime. They are ideal for documenting order statuses, user account states, deployment phases, approval workflows, and any system where entities move through discrete states with defined transitions.
C4 Diagrams: Software Architecture
C4 diagrams follow the C4 model for software architecture, providing views at three levels of abstraction: context (system-level), container (service-level), and deployment (infrastructure-level). Use them when you need formal architecture documentation that follows a widely recognized standard.
Gantt Charts: Project Timelines
Gantt charts visualize project schedules with tasks, dependencies, milestones, and completion states. They are useful for sprint planning documents, release roadmaps, and any Confluence page that tracks time-based work.
Git Graphs: Version Control Strategy
Git graphs visualize branching strategies, merge patterns, and release workflows. They are particularly useful in contributor guidelines and DevOps documentation where teams need to agree on a branching model.
Mindmaps: Brainstorming and Knowledge Mapping
Mindmaps are hierarchical tree diagrams for brainstorming, topic breakdowns, and knowledge organization. Use them in meeting notes, research summaries, and planning documents where you need to capture and organize ideas quickly.
Timeline: Chronological Events
Timelines show events in chronological order, organized by sections. Use them for release histories, incident post-mortems, project milestones, and any documentation where sequence matters but dependency tracking (as in Gantt charts) is not needed.
Less Common but Valuable Diagram Types
The remaining diagram types serve niche but important purposes in software documentation:
Requirement diagrams link requirements to design elements, useful for traceability matrices and compliance documentation.
User journey maps combine tasks with satisfaction scores (1-5), making them useful for UX documentation and customer experience mapping.
Quadrant charts categorize items on two axes, ideal for prioritization matrices, risk assessments, and technology radar visualizations.
Pie charts and XY charts present quantitative data -- survey results, budget breakdowns, performance metrics, and similar numerical information.
Treemaps show hierarchical data as nested rectangles, useful for visualizing codebase size by directory, budget allocation, or test coverage distribution.
Sankey diagrams visualize flow quantities through a system, making them ideal for data pipeline documentation and resource flow analysis.
Ishikawa (fishbone) diagrams support root cause analysis with categorized causes feeding into a central problem statement -- a standard tool in incident post-mortems.
Packet diagrams document network protocol structures with bit-level field positions, essential for networking and IoT teams.
Kanban boards provide a simple board-style task visualization directly in Confluence, useful for lightweight project tracking.
Radar charts compare multiple entities across several axes, helpful for technology evaluations and skill gap analysis.
TreeViews visualize file and folder hierarchies, useful for project structure documentation and configuration walkthroughs.
Venn diagrams show set overlaps, useful for stakeholder analysis and capability mapping.
Block diagrams offer structured component layouts with column control, serving as a middle ground between flowcharts and C4 diagrams.
ZenUML provides an alternative syntax for sequence diagrams with typed participants (Actor, Database, Participant), preferred by teams already familiar with ZenUML notation.
How Mermaid Diagrams Render in Confluence
Understanding how Mermaid Plus for Confluence handles rendering helps you write better diagrams and troubleshoot issues faster.
Live preview. When you insert a Mermaid macro and open the configuration panel, the left column shows a real-time preview of your diagram. As you type or modify settings, the preview updates instantly. This means you can catch layout problems, syntax errors, and visual issues before saving the macro to the page.
Cached SVG output. When you save a diagram, Mermaid Plus renders it to a static SVG and caches the result. Page visitors see the cached SVG, not a client-side JavaScript rendering. This approach has two major benefits: pages load faster because no JavaScript execution is needed for diagrams, and diagrams display consistently across all browsers and devices.
Dark mode support. Mermaid Plus automatically adapts diagrams to Confluence's dark/light mode. When you save a diagram, the current Confluence theme is recorded. When the page loads, if the theme has changed, text and background colors are adjusted for readability. You can also manually choose a theme (default, dark, forest, or neutral) for each macro instance.
Custom colors and fonts. The settings panel provides five customizable colors (node, text, border, line, background) with visual color pickers, plus font family and size controls. These settings give you fine-grained control over how diagrams look without modifying the Mermaid code itself.
Output size. You can control how large the diagram appears on the Confluence page with four size options: Small (0.5x), Medium (1x, default), Large (1.5x), and X-Large (2x). This is useful when a diagram needs to be larger for a presentation page or smaller to fit alongside text.
For complete details on configuration options, themes, and settings, see the Mermaid Plus for Confluence usage guide.
Tips for Writing Diagrams That Work Well in Confluence
Start with a template. The Quick Templates panel provides working code for all 26 diagram types. Click any template to load it into the editor, then modify it to match your needs. This is faster than writing from scratch and helps you avoid syntax errors.
Keep diagrams focused. Each diagram should tell one story. If your flowchart has grown to 20+ nodes, consider splitting it into two or three smaller diagrams that each cover a specific part of the process. Focused diagrams are easier to read, easier to maintain, and render faster.
Use subgraphs to organize complex diagrams. In flowcharts, subgraphs group related nodes into bordered sections. This improves both visual organization and layout efficiency, because the rendering engine treats each subgraph as a single unit during placement.
Choose the right direction. Flowcharts support four directions. Top-down (TD) works best for hierarchical processes. Left-right (LR) is better for linear pipelines and stage-based flows. Experiment with both to find the orientation that makes your diagram easiest to follow.
Test in both light and dark modes. Confluence users may have either theme active. Check that your diagrams are readable in both modes by toggling the Confluence theme and reviewing the rendered output. If you use custom colors, ensure they have sufficient contrast against both light and dark backgrounds.
Validate syntax before publishing. Use the live preview in the configuration panel to catch errors before saving. For complex diagrams, consider validating in the Mermaid Live Editor at mermaid.live first, then pasting the validated code into Confluence.
Related Resources
- Mermaid Plus for Confluence -- Usage Guide -- complete documentation for the Mermaid Plus app with templates, themes, and customizable settings
- Mermaid Syntax Cheat Sheet for Confluence -- quick reference for Mermaid syntax with copy-paste examples
- How to Create Sequence Diagrams in Confluence -- step-by-step guide for documenting API interactions and service communication
- How to Create Class Diagrams in Confluence -- tutorial for object-oriented design documentation with class hierarchies and relationships