Mermaid in Confluence Not Rendering? Fixes & FAQ
Mermaid diagrams have become a go-to way for engineering and product teams to document architectures, workflows, and data models directly inside Confluence pages. Instead of exporting images from a desktop tool and re-uploading every time something changes, you write a few lines of text and the diagram renders inline. But when something breaks — a diagram shows raw code, colors disappear, or the whole page grinds to a halt — it can be frustrating to figure out where the problem lies.
This FAQ covers the most common issues teams encounter when using Mermaid inside Confluence, with specific fixes, syntax tips, and performance guidance. Whether you are troubleshooting a single broken flowchart or standardizing diagram practices across a large organization, the answers below should get you back on track quickly.
Why does my Mermaid code show raw text instead of a diagram?
When you see raw Mermaid syntax on the published page instead of a rendered diagram, the root cause is almost always that the Mermaid macro is not properly inserted or the app is not enabled. In the Confluence editor, type /mermaid and select the Mermaid Plus macro from the dropdown. If that command does not appear, the Mermaid Plus app is either not installed or not enabled for your space.
To resolve this, navigate to Confluence Administration > Apps and confirm that Mermaid Plus for Confluence is listed and active. If you are a space admin but not a site admin, check whether the app has been restricted to certain spaces. In some cases, the macro appears in the editor but the published page still shows raw text — this typically means the app's JavaScript bundle is being blocked by a Content Security Policy or an ad-blocker browser extension. Try opening the page in an incognito window to rule out browser extensions, and ask your Confluence administrator to verify the CSP headers allow scripts from the app domain.
If you recently upgraded Confluence, verify that the Mermaid Plus app version is compatible with your new Confluence version. App vendors usually release compatibility updates within a few days of a major Confluence release.
My diagram renders in the editor but not on the published page. How do I fix it?
This is one of the most frequently reported issues, and it usually comes down to script loading behavior. The Confluence editor and the published page view use different rendering pipelines. In the editor, the Mermaid app can inject its JavaScript directly. On the published page, scripts may be lazy-loaded or deferred for performance reasons, which can cause a race condition where the page HTML loads but Mermaid never initializes.
First, try clearing your browser cache and doing a hard refresh of the published page. If that works, the issue was a cached version of the page that predated your macro insertion. If the problem persists, check whether your Confluence theme or any custom HTML injections are interfering with the Mermaid script tags. Some third-party themes strip inline scripts for security.
Another common cause is a mismatch between the app version and the Confluence version. Check the Mermaid Plus release notes for compatibility information. If you are on Confluence Cloud, the app updates automatically, but on Confluence Data Center you may need to manually approve the update in the Universal Plugin Manager. Republishing the page after an app update often resolves the issue.
I get a "Syntax error" in my Mermaid diagram. How do I debug it?
Syntax errors are by far the most common problem for teams new to Mermaid. The fastest way to diagnose one is to paste your code into the Mermaid Live Editor at mermaid.live. The Live Editor renders your diagram in real time and highlights the exact line where parsing fails, which removes the guesswork entirely.
Here are the syntax errors teams encounter most often:
Unclosed subgraph or block. Every subgraph keyword must have a matching end. Mermaid will not throw an error on the subgraph line — it will fail at the end of the file when it runs out of input without finding end. Always count your subgraph and end pairs.
flowchart TD
subgraph A
node1 --> node2
end
subgraph B
node3 --> node4
end
Wrong indentation. Unlike Python, Mermaid does not require indentation, but inconsistent indentation in class diagrams and sequence diagrams can cause parsers to misread your intent. Keep indentation purely for readability and do not mix tabs and spaces.
Missing arrows or operators. In flowcharts, every connection needs a valid arrow operator (-->, ---, ==>, -.-, and so on). A bare node1 node2 with no operator between them will produce a syntax error.
Unsupported diagram features. Mermaid adds new features regularly, but the version bundled in your Confluence app may lag behind the latest upstream release. If a feature works in the Live Editor but fails in Confluence, check which Mermaid version your app uses and consult the Mermaid changelog for when that feature was introduced.
Common Mermaid syntax errors
| Error message or symptom | Cause | Fix |
|---|---|---|
| "Parse error on line X" | Unclosed subgraph or missing end | Add a matching end for every subgraph block |
| Diagram renders partially and stops | Invalid arrow operator or typo in a node reference | Double-check all -->, ---, and node IDs for typos |
| "Error: Lexical error" | Special characters in labels not wrapped in quotes | Wrap label text containing ()[]{}> in double quotes: A["Label (with parens)"] |
| Entire diagram shows as code | Macro not inserted or app disabled | Type /mermaid in editor; verify app is installed and enabled |
| Blank white space where diagram should be | JavaScript blocked by CSP or browser extension | Test in incognito; ask admin to allow script domains in CSP |
Colors not applied from style statements | Style references node ID that does not exist | Ensure the style line references the exact node ID used in the diagram |
| Sequence diagram participants overlap | Too many participants for default width | Use shorter aliases or reduce participant count; split into two diagrams |
Supported diagram types
Mermaid supports a wide range of diagram types, and Mermaid Plus for Confluence exposes all of them through a single macro. The following table lists each diagram type, its keyword, and a brief description of when to use it.
| Diagram type | Keyword | Use for |
|---|---|---|
| Flowchart | flowchart | Process flows, decision trees, system architecture. Supports direction flags: TD (top-down), LR (left-right), BT (bottom-top), RL (right-left) |
| Sequence | sequenceDiagram | Interactions between actors/services over time, API call flows, step-by-step processes |
| Class | classDiagram | Object-oriented class hierarchies, data models, UML-style relationships |
| State | stateDiagram-v2 | State machines, lifecycle diagrams, status transitions |
| Entity-Relationship | erDiagram | Database schemas, entity relationships, data architecture |
| Gantt | gantt | Project timelines, milestone tracking, sprint planning |
| Pie | pie | Proportional data, survey results, budget breakdowns |
| Mindmap | mindmap | Brainstorming trees, hierarchical topic breakdowns, knowledge maps |
| Timeline | timeline | Chronological events, release histories, project milestones |
| Gitgraph | gitGraph | Branching strategies, release workflows, Git collaboration models |
| C4 | C4Context, C4Container, C4Deployment | Software architecture diagrams following the C4 model |
| Sankey | sankey-beta | Flow of resources, budget allocation, energy transfers between categories |
| Block | block-beta | Block diagrams for system components and their relationships |
| Quadrant | quadrantChart | Priority matrices, risk/effort analysis, two-axis categorizations |
Not every diagram type supports every feature. For example, style statements work in flowcharts and sequence diagrams but have limited support in pie and gantt charts. When in doubt, test in the Mermaid Live Editor first.
How do I control the layout direction of my flowchart?
Flowcharts in Mermaid default to top-down (TD), but you can change the orientation by specifying a direction flag after the flowchart keyword. The four supported directions are:
- TD or TB — Top to Down (default). Best for hierarchical processes and org charts.
- LR — Left to Right. Ideal for linear pipelines, CI/CD stages, and timeline-like flows.
- BT — Bottom to Top. Useful for bottom-up dependency charts and reverse traceability.
- RL — Right to Left. Rare but helpful for RTL language layouts or reverse data-flow diagrams.
Example:
flowchart LR
A[Source] --> B[Build] --> C[Test] --> D[Deploy]
Choosing the right direction can make a significant difference in readability. Wide, shallow diagrams usually work best with LR, while deep, branching structures are easier to follow with TD. If your diagram has more than three levels of nesting, consider splitting it into subgraphs or multiple linked diagrams.
Why are colors not showing consistently in my Mermaid diagrams?
Color inconsistencies in Mermaid diagrams usually stem from one of three sources: theme conflicts, incorrect style syntax, or CSS overrides from the Confluence space.
Theme conflicts. Mermaid Plus for Confluence ships with built-in themes that automatically adapt to Confluence's light and dark modes. If you hardcode colors using style statements or classDef rules, those colors may look fine in light mode but become invisible against a dark background. The recommended approach is to use semantic color names or test your diagrams in both modes using the theme toggle in Mermaid Plus settings.
Incorrect style syntax. Style statements in Mermaid must reference exact node IDs and use valid CSS properties. A common mistake is styling a node ID that includes special characters without quoting it correctly. For example:
flowchart TD
A["My Node"] --> B["Other Node"]
style A fill:#f9f,stroke:#333
Note that the style statement references the node ID A, not the label text "My Node". Mixing these up will silently fail — the style is simply not applied.
CSS overrides from Confluence. Space administrators can inject custom CSS that may override Mermaid's default styles. If your diagrams look correct in one space but broken in another, compare the space stylesheets. Remove or scope any global rules that target svg, path, or rect elements, as these will interfere with Mermaid's rendered output.
How can I improve Mermaid rendering performance?
Performance becomes a real concern when diagrams grow large or when a single Confluence page contains multiple complex diagrams. The guidelines below will help keep your pages responsive.
Keep individual diagrams under 100 nodes. Beyond roughly 100 nodes, client-side Mermaid rendering starts to degrade noticeably, especially on older hardware or mobile devices. If your architecture diagram has grown to 150+ nodes, split it into logical subsystems using subgraphs or break it into multiple separate diagrams on the same page.
Use cached SVG for large diagrams. Mermaid Plus for Confluence renders diagrams to cached SVG, so page visitors see the pre-rendered result without needing client-side JavaScript execution on every page load. This keeps pages fast even with multiple diagrams.
Avoid deeply nested subgraphs. Each level of nesting increases the layout computation time. If you have subgraphs three or four levels deep, consider flattening the structure or representing the outer containers as separate linked diagrams.
Minimize simultaneous diagrams on one page. A Confluence page with ten large flowcharts will be slow regardless of how well each individual diagram is written. If you need many diagrams on a single page (for example, a design-decision document), consider using collapsible sections or a table-of-contents structure that spreads diagrams across child pages.
Use descriptive but concise labels. Long labels force the layout engine to allocate more space and can result in awkward node sizes. Aim for labels under 30 characters where possible, and use line breaks (<br/>) inside labels rather than relying on the engine to wrap text.
My Mermaid diagrams are too large or overlap other content. What can I do?
Oversized or overlapping diagrams are usually a layout problem rather than a syntax one. Here are the most effective fixes.
Adjust the direction flag. A diagram that sprawls horizontally in LR mode may fit cleanly in TD mode, or vice versa. Experiment with different direction flags to find the orientation that best uses the available page width.
Shorten labels and reduce node count. Every additional word in a label increases the rendered width of that node. Use abbreviations or move detailed descriptions into tooltips or surrounding text.
Use subgraphs to group related nodes. Subgraphs not only organize your diagram logically — they also help the layout engine allocate space more efficiently by treating groups as single units during the initial placement pass.
Configure the macro's width and scale settings. Mermaid Plus for Confluence lets you set a maximum width and a scale factor for each macro instance. If your diagram is rendering at full size and overflowing the page container, set a max-width of 100% and enable auto-scaling so the SVG fits within the available space.
Split into multiple diagrams. If none of the above work, the most reliable solution is to break the diagram into two or three smaller diagrams connected by descriptive text. This also improves readability for your audience, since a single massive flowchart is harder to follow than a series of focused ones.
What features does Mermaid Plus for Confluence provide?
Mermaid Plus for Confluence extends the base Mermaid library with features specifically designed for enterprise Confluence environments.
Macro insertion. Type /mermaid in the Confluence editor to insert the macro instantly. The macro opens an inline code editor with syntax highlighting, so you can write and preview your diagram without leaving the page.
Custom themes. The app includes multiple built-in themes (default, dark, forest, neutral) and supports custom theme definitions that space admins can configure. This ensures your diagrams match your organization's visual identity.
Light and dark mode. Mermaid Plus automatically detects whether a user is viewing Confluence in light or dark mode and applies the appropriate theme. You can also force a specific theme per macro if you need consistent colors regardless of the user's preference.
Cached SVG rendering. Instead of rendering every diagram in the browser on each page load, Mermaid Plus renders diagrams to cached SVG. This keeps pages fast because the Mermaid.js library is only loaded during editing -- not when viewing pages.
Quick tips for writing reliable Mermaid diagrams
- Always validate your syntax in the Mermaid Live Editor before pasting into Confluence.
- Use double quotes around any label that contains special characters.
- Count your
subgraphandendpairs every time you edit a flowchart. - Keep individual diagrams under 100 nodes for best performance.
- Test your diagrams in both light and dark Confluence themes before publishing.
- Use
classDefandstylestatements instead of external CSS for coloring nodes. - Choose the right diagram type for the job — do not force a flowchart when a sequence diagram or ER diagram communicates the idea more clearly.
Related resources
- Mermaid Plus for Confluence — documentation
- Mermaid Plus Diagrams for Jira — Mermaid in Jira issues
- Create Mermaid diagrams in Confluence — complete how-to guide with examples
- Excalidraw & Mermaid Visual Editor — combine freeform and structured diagrams