Mermaid diagrams in Confluence — FAQ & Troubleshooting

Q: My Mermaid code shows raw text, not diagrams. Why? A: The Mermaid plugin may not be enabled on the page or the macro is missing. Ensure the Mermaid macro is installed and used.

Q: Diagrams render in editor but not on the page. A: Check that rendering is allowed for viewers and that the page theme loads Mermaid assets. Some themes lazy-load JS.

Q: I get "Syntax error". A: Validate the code in the Mermaid Live Editor. Common issues: unclosed blocks, wrong indentation, or unsupported statements.

Q: Diagrams are too large or overlap. A: Use smaller labels, sections, or adjust the scale/outputSize settings in the plugin.

Q: Colors not showing consistently. A: Use theme-compatible color values and avoid CSS overrides from Confluence space styles.

Q: Performance tips? A: Keep diagrams simple; use static snapshots for very large or complex diagrams to reduce client rendering cost.