Known limitations

The limits and constraints to know before you build large diagrams or roll the app out. Each one says why it exists and what to do instead.

Limits

Limit	Value	Applies to
File size for import	5 MB	Import diagrams
Diagrams added from one link or file	20	Import
Length of one imported or found diagram	100,000 characters	Import, and Mermaid code blocks on pages and work items
Mermaid code blocks shown per Jira work item	20	Edit Mermaid code blocks in Jira
Jira comments searched for Mermaid code	The newest 1,000	Jira
Length of a Jira description or comment	32,767 characters, set by Jira	Editing a code block in place
Snippets in the gallery	35	Start from a snippet

There is no limit on the number of diagrams per page, work item or site, and no per-user quota.

Very large diagrams draw slowly. A diagram with hundreds of nodes takes longer to draw and is hard to read on a page. Split it into several focused diagrams in one macro or panel, and readers can open each one full screen.
Mermaid 12.1 syntax only. Diagram types and features added to Mermaid after version 12.1 work once the app updates its bundled Mermaid.
Labels allow only basic HTML. Tags such as <b>, <i> and <br> work. Scripts, event handlers and click links to JavaScript are removed for security.
Icons come from two built-in sets. Architecture diagrams can use logos: and mdi: icons only. The app loads nothing from outside Atlassian, so other icon packs aren't available.
Older diagrams look different since Mermaid 12. The default look and layout changed. See Keep the previous look.

Mermaid 12 needs a current browser: Chrome, Edge or Firefox released since early 2024, or Safari 17.4 or later (iOS 17.4 on iPhone and iPad). Older browsers can't draw diagrams.

Templates aren't supported. Diagrams are stored with a page, so the macro shows "This diagram can't be loaded here" in a space or page template. Add the macro after you create the page.
Diagram changes don't create page versions. They're stored as page attachments. Restoring an older page version keeps the newest diagrams. Earlier versions of a diagram stay in the page's attachment history.
PDF and Word exports show one image per macro. Confluence exports show each macro's first diagram as a light-colored image.
Diagram text isn't searchable. Labels inside diagrams don't appear in Confluence search results.
Converting code blocks needs a clean page. A page with unpublished changes, or in a space that needs approval before publishing, can't be converted from Mermaid diagrams on this page.

Diagrams show only when a work item is open. Board cards and list views don't show them.
Panel diagrams have no history. They're stored by the app, so they don't appear in the work item's attachments or history, and aren't included in Jira exports.
Diagram text isn't searchable. Labels inside panel diagrams don't appear in Jira search results.

Atlassian Cloud only. Mermaid Diagrams is a Forge app and isn't available for Confluence or Jira Data Center.
Separate apps for Confluence and Jira. Forge apps are built for one product, so each product needs its own app and license.