grafloria

Blog / Use cases

When your Mermaid diagram grows up

August 22, 2026 · use cases · mermaid

mermaid diagrams

If you've ever shipped a Mermaid diagram in a README, you know the arc. At ten nodes it's perfect — text in git, rendered everywhere, reviewed as a diff. At forty nodes it's a ribbon three screens wide with text nobody over thirty can read, and you're googling things no one should have to google.

The hacks we've all done

We keep meeting the same three workarounds, because we did them too:

  • The invisible node trick. A node fans out to eight children, the layout goes horizontal forever, so you insert fake intermediate nodes to force wrapping. Now your diagram's source lies about your system to make the picture tolerable.
  • The direction shuffle. flowchart LR — too wide. TD — too tall. Back to LR, but with subgraphs, which now refuse to align the way you want. There's a whole genre of Stack Overflow questions about nudging Mermaid's layout with syntax that was never meant to be a layout language.
  • The print surrender. Someone asks for it on paper. The SVG scales the whole drawing to fit, so a big diagram means small text by construction — and you end up screenshotting quadrants.

None of this is Mermaid's fault. Text-to-diagram is the right tool for documentation — that's why we made Grafloria speak it rather than replace it. The problem is the moment a diagram crosses from documentation to thing people work with. Text has no verb for "drag this node out of the way".

Keep the text. Add hands.

Grafloria reads your Mermaid source into a live, editable canvas — same nodes, same edges, now draggable:

import { render } from '@grafloria/element';

const api = render({ nodes: [], edges: [] }, document.getElementById('canvas'));
api.loadText(mermaidSource);      // the same text your README renders

And here's the part that makes it a workflow instead of a migration: the round trip is lossless and the text stays valid Mermaid. Drag nodes into the arrangement your team actually thinks in, then:

const text = api.exportText();
// still renders in GitHub — your positions ride in a %%grafloria:document
// comment that Mermaid ignores and Grafloria reads back

Your hand-arranged layout survives a commit, a review, and a re-import. The file in git is still a Mermaid file. Nobody on your team has to install anything to keep reading it.

The forty-node problems, specifically

  • Too wide? Run a real layout engine on it — await api.getEngine().layout('dagre', { direction: 'TB' }), or 'elk' for the hard graphs. Then fix the two nodes it got wrong by dragging them.
  • Too small to print? await api.export('pdf') is a vector PDF — text stays text, crisp at any paper size, and your PDF viewer's poster mode handles multi-page.
  • Unsupported diagram type? We support flowchart, erDiagram, classDiagram and stateDiagram, verified against real Mermaid v11 in CI — and anything else is refused loudly with result.unsupported, never rendered wrong.

Try it with your own diagram: paste your Mermaid into the live round-trip demo, or start with the Mermaid & the text format guide. The honest comparison — including when to just stay with Mermaid — is at alternatives/mermaid.