Use a Mermaid visual editor without losing the source
Improve Mermaid diagram layout with visual editing while keeping code reviewable. Learn when to use automatic layout, manual placement, and portable exports.
A Mermaid visual editor is useful when the source says the right thing but the drawing is difficult to follow. Code is good for precise structure; direct manipulation is often faster for arranging a presentation.
The goal is to improve reading order while preserving meaning. Moving a box should not accidentally change the relationship it represents.
Begin with a correct graph
flowchart LR
Client --> API
API --> Cache
API --> Database[(Database)]
API --> Queue
Queue --> Worker
Worker --> DatabaseBefore arranging anything, read every arrow aloud. Does API-to-Cache mean a read, a write, or both? Is the queue path asynchronous? Add labels where a reader might infer the wrong behavior.
Once the graph is correct, choose an overall direction. Left to right often fits a request path; top to bottom may suit a narrow documentation column. A layout that looks good on a large monitor can still fail in the place it will be embedded.
Use automatic layout as the starting point
Automatic layout is a useful first draft because it responds to structural changes. Try the available layout choices before placing every node manually. In Flowgraph Studio, the Layout tab offers several engines (ELK layered for a clean hierarchy, ELK stress for an organic network, ELK tree, ELK radial for rings around a hub, Grid, and Mermaid's default Dagre), a direction override, the line style, and spacing between nodes and between ranks. Sometimes changing direction or splitting an overloaded view solves the problem more cleanly than individual adjustments.
Then identify the reading problem: crossing edges, a remote label, or an asynchronous branch that looks like part of the main request. Make a targeted correction rather than rearranging the whole graph without a reason.
Apply manual editing deliberately
In Flowgraph Studio, switch the top-bar toggle from Code to Manual to edit on the canvas. In flowcharts and state diagrams you can drag nodes, resize them, drag a connection's end to another side of its node, and move a node's text off-centre. ER and class diagrams let you move boxes and draw relationships with their cardinality or multiplicity. Sequence diagrams keep Mermaid's strict layout: you reorder participants and move messages up or down rather than placing them freely.
Keep the code visible while editing. Check whether an action changed a label, relationship, or only the arrangement. Use undo if the operation did more than intended.
Flowgraph stores a manual arrangement in a %% flowgraph-layout: comment line in the code. Flowgraph exports, the render API, and shared links keep that arrangement. Other Mermaid tools ignore the comment and compute their own layout, so a portable source file may render with a different arrangement elsewhere. Once nodes are placed by hand, the engine, direction, and spacing settings no longer move them; Arrange automatically in the Layout tab hands the layout back, and deleting the comment line does the same.
Review the actual output
Export a preview at the size readers will see. Check labels, contrast, edge direction, and whitespace around the diagram. If a node needs a paragraph to explain it, consider shortening its label and moving detail into surrounding prose.
For a fixed presentation appearance, use an exported image and retain the Mermaid source beside it. For a destination that renders Mermaid itself, test the source in that destination rather than assuming identical behavior.
Open Flowgraph Studio to try the example, or review the flowchart syntax guide before editing. A successful layout makes the structure easier to read while leaving the model understandable in text.
More guides
- Animate a Mermaid diagram as a short technical explanationTurn a static Mermaid flow into a captioned explanation. Plan the story, select GIF or video output, and check that animation preserves the system's meaning.
- Explain an Azure background-job architecture with MermaidDraw an illustrative Azure job-processing architecture with API, queue, worker, and storage boundaries. Explain acknowledgment, completion, and failure handling.
- Build a consistent technical carousel with a reusable brand kitCreate readable technical carousel slides using a reusable brand kit. Keep colors, typography, diagrams, and export checks consistent across the series.