Best practices · Large diagrams
How to Keep Large Mermaid Diagrams Readable
Every architecture and ER diagram starts clean and ends as spaghetti — forty nodes, crossing edges, labels nobody can read at page width. Exporting at higher resolution does not fix this; the diagram is fighting its own size. What works is restructuring: split it into focused views, group what belongs together, and export a format readers can zoom.
No signup · No watermark · Local browser rendering · Zoomable SVG and high-resolution PNG export
When is a Mermaid diagram too big?
A documentation diagram works when a reader can trace any edge without losing their place. That usually breaks down somewhere between 12 and 15 main boxes — beyond that, the layout engine starts crossing edges, labels shrink below reading size at page width, and the diagram stops explaining and starts intimidating. The all-in-one system poster feels complete, but almost every reader only needs one slice of it. Several small diagrams that each answer one question beat one large diagram that answers none.
From spaghetti to readable views
- 1
Split by subsystem or journey
Cut along natural seams: one diagram per subsystem, bounded context, or user journey. A top-level overview with 5-10 boxes shows how the pieces relate; each piece then gets its own detailed diagram. Readers navigate between small views instead of panning one huge one.
- 2
Group with subgraphs
Inside each flowchart, wrap related nodes in subgraph blocks — services in one box, data stores in another. Grouping cuts perceived complexity even when the node count stays the same, and consistent short names keep boxes compact.
- 3
Move detail out of the diagram
Long labels are a sign the diagram is doing prose's job. Keep node labels to a few words, and put payload formats, edge cases, and configuration in the text next to the diagram. The picture shows the structure; the words carry the detail.
- 4
Export SVG so readers can zoom
For the diagrams that must stay big — full ER models, system overviews — export SVG. Vector output stays sharp at every zoom level, so readers can dive into a corner without the whole image degrading. If the platform needs raster, use PNG at 4x.
Export your diagram here
Paste your Mermaid code below, pick a style, and download the image. Everything renders locally in your browser — no signup, no watermark.
Export controls activate after your diagram renders locally.
Structure patterns that scale
One top-level diagram showing subsystems as single boxes, linked to a focused diagram per subsystem. Each stays under ~15 nodes and answers exactly one question.
Mermaid flowcharts support nested subgraph blocks with their own labels. Use them to box services, layers, or domains so the eye reads groups first, nodes second.
Wide diagrams that overflow docs pages often just have the wrong flow direction. Switching a flowchart between LR and TD trades width for height — try it before splitting.
FAQ
Questions about this workflow
How many nodes should a Mermaid diagram have?+
For documentation, aim for 15 or fewer main boxes per diagram. Beyond that, edges start crossing and labels shrink below comfortable reading size at page width. If you are past the limit, split by subsystem rather than shrinking the font.
My ER diagram has 40+ tables — what do I do?+
Split it by domain: one erDiagram per bounded area (orders, billing, identity), each showing its tables plus the foreign keys that cross into neighboring domains. Keep one high-level diagram that only shows the domains and their relationships.
My diagram is too wide for the docs page — how do I fix it?+
Change the flow direction first: flowchart LR becomes flowchart TD, trading width for height. If it is still too wide, the diagram is probably carrying more than one story — split it. Only then reach for a wider export.
Can I export just one part of a big Mermaid diagram?+
Not from the rendered image — Mermaid exports the whole diagram. Copy the relevant nodes into a separate, smaller diagram instead. Since Mermaid is text, extracting a slice is a copy-paste, and you can keep both versions in the same doc.
Should a big diagram be SVG or PNG?+
SVG. Large diagrams are exactly where vector output earns its keep: readers zoom into corners and the text stays sharp. Use PNG at 4x only when the destination platform cannot display SVG.