Mermaid Diagram Renderer

Diagram Source That Refuses to Render

• Mixing arrow styles from different diagram types: Pasting a sequence-diagram arrow like ->> into a flowchart, or a flowchart arrow like --> into a sequence diagram, produces a parser error instead of a diagram — each diagram type has its own grammar and they are not interchangeable.
• Unquoted node labels containing special characters: A node written as A[Deploy (canary)] can confuse the parser because parentheses have syntactic meaning in flowchart node shapes; wrapping the label in quotes, A["Deploy (canary)"], resolves it.
• Forgetting the diagram-type declaration on the first line: Every Mermaid block must start with a declaration such as flowchart TD, sequenceDiagram, or gantt — omitting it, or adding blank lines before it, causes the renderer to fail silently with no diagram output at all.
• Reusing a node ID with two different labels: Writing A[Build] in one line and A[Compile] later in the same flowchart doesn't create two nodes — Mermaid treats both as the same node and keeps whichever label it parsed last, which quietly breaks diagrams that were supposed to show two distinct steps.

Keeping a Text-Based Diagram Maintainable

• Store the source next to the code it documents: Keep a runbook's .mmd block in the same repository and pull request as the workflow it describes, so the diagram is reviewed and updated alongside the logic change rather than drifting out of sync in a separate wiki.
• Use subgraphs to group related nodes: For any flowchart with more than roughly 15 nodes, wrap logically related steps in subgraph blocks — it keeps the auto-layout algorithm from producing a tangled mess of crossing lines.
• Prefer short, consistent node IDs with descriptive labels: Use IDs like A, B, C for structure and put the human-readable text inside the label brackets — this keeps the source diffable in version control even when labels change.
• Load one of the built-in DevOps examples before starting from scratch: The diagram-type chips above the editor include realistic CI/CD, Kubernetes, and Git-branching examples that are faster to modify than to write from a blank editor.

What Rendering Untrusted Diagram Source Can Expose

This tool initializes Mermaid with its security level set to loose rather than the stricter strict or antiscript modes, because several diagram features — clickable nodes with click A "https://..." callbacks, and HTML-formatted labels — only work in loose mode. That tradeoff is fine when you are writing your own diagrams, but it means you should never paste Mermaid source copied from an untrusted wiki page, chat message, or ticket directly into this tool and treat the output as safe, since loose mode permits embedded links and markup that a stricter mode would strip. If you need to render diagram source of unknown origin, read through the raw text first the same way you would review a shell script before running it.

On the positive side, everything happens client-side — the Mermaid syntax you type never leaves your browser, there is no server round-trip, and the exported SVG or PNG contains only the rendered shapes and text with no residual script tags, making the output itself safe to paste into documentation platforms.

When a Diagram Gets Too Big for the Browser to Lay Out

Mermaid's auto-layout engine computes node positions and edge routing on every render, and that computation scales worse than linearly as node and edge count grows — a flowchart with 100+ nodes and dense cross-connections can take a noticeable moment to lay out and may produce a cramped, hard-to-read result even when it renders successfully. Gantt charts with many overlapping task bars and sequence diagrams with a large number of participants hit similar limits, since every additional participant widens the diagram and every additional message adds a row. If a diagram becomes sluggish to edit or hard to read, that's usually a signal to split it: break one large flowchart into several smaller ones linked from a table of contents, or use subgraphs to collapse detail that isn't relevant to the current audience.

Rendering the Same Diagram Without a Browser

Everything this tool does interactively — parse Mermaid syntax and rasterize it to SVG or PNG — can also be done non-interactively with the official mmdc command-line tool from the @mermaid-js/mermaid-cli npm package, which drives a headless Chromium instance under the hood: mmdc -i diagram.mmd -o diagram.svg. That CLI path is what you want once a diagram needs to be regenerated automatically — for example, a CI job that renders every .mmd file in a docs folder to SVG on every merge to main, keeping published architecture diagrams in sync with their source without anyone manually re-exporting them. Use this browser tool for the fast, visual iteration loop while you're writing or editing a diagram, and reach for mmdc in a Docker image or CI pipeline once you need the same rendering step to run unattended and repeatably.

Frequently Asked Questions