A mermaid diagram visual editor that keeps the text

A mermaid diagram visual editor, for a repo that keeps diagrams in git, is a code pane beside a live preview. You change the text, the picture updates, and the file you commit is still the source.

People ask for that and for drag-and-drop in the same breath. They want to grab a box, and they want the diff to stay readable. Those are different tools. MermaidViewer is the first kind: a code editor with a live preview and an AI assist. It is not a Visio clone, and it does not grow a drag canvas because a flowchart got popular. If you need a specific Visio behavior, check your version of Visio. I can't honestly describe its current stencils from memory, and I won't fake it.

My opinion is plain. Start in text. Use the AI when the blank page is the problem, not when you already know the sentence the diagram should say.

Code on one side, the picture on the other

Open the editor. No signup. The text is on one side and the preview is on the other. You type flowchart TD, you add a node, the preview draws it. You rename a label, the box renames. You break a quote, the preview tells you instead of drawing a confident wrong chart.

That side-by-side loop is the visual part. You are not guessing what the text will become, and you are not dragging a box whose position will be thrown away the next time the layout runs. Mermaid's flowchart layout is a graph layout. It places nodes. If you wanted the box three pixels to the left, you wanted a different tool. If you wanted the box to say "Reviewer" instead of "Manager," you wanted this one.

I keep the preview visible while I edit because I mistype arrows. --> and --- are both legal and they don't mean the same thing in every diagram type. Seeing the line appear, or not appear, is faster than reading the source twice. The preview is not a design review. It's a parse check with a picture attached.

Share links exist if you need someone else to open the same text without the repo. I still put the text in the pull request. A link expires as a habit even when the URL still resolves. The commit doesn't.

Dragging boxes is a different job

A pure drawing tool stores positions. You place a box, it stays, and the file remembers coordinates. That's a good job when the picture is a poster, a floor of a network, or a slide someone will nudge for an hour. It is a bad job when the picture is a policy and the review is about which branch is "no."

I don't pretend this site has a drag canvas hiding in a menu. If a page told you to drag the diamond onto the arrow, it was talking about another product. Here you write the diamond: gate{Over the limit?}. The preview places it. You don't get a handle.

That sounds like a limitation if you came from a whiteboard. It is a limitation. It's also why the file merges. Two people can edit two labels and git can show both hunks. Two people dragging the same box in a binary drawing file produce a conflict that looks like noise, or a silent overwrite, depending on the tool. Check that tool's version before you take my word for how it merges. I only know what happens to text.

If your team already thinks in drag-and-drop, the notes on drawing Mermaid by hand versus generating it are the adjacent argument. This page is about the editor you have once you've chosen text.

When a pure GUI is the better afternoon

Use a GUI, and keep it, when the layout is the content. A conference poster, a one-off executive picture with a logo in the corner, a map of a physical room. Mermaid will fight you, because it wants a graph and you want a composition. I've wasted an hour adding invisible edges to pin a box in a corner. The hour was the lesson. Export isn't going to turn a graph layout into a poster tool.

Use a GUI when the audience will never accept a text file and will also never send you edits. A vendor workshop where the artifact is a photo of a whiteboard is that case. Transcribing it into Mermaid afterwards is optional, and it's worth it only if the decision will be maintained. Most workshop photos shouldn't be maintained. They should be summarized in a paragraph.

Use a GUI when you need a symbol set Mermaid doesn't have. Precise electrical stencil work, for example, is not a flowchart with extra shapes. I won't list another product's libraries. If you're comparing editors that do keep Mermaid as the source, the roundup of Mermaid editors is the page for that, and I'd rather you read it than trust a feature table I might remember wrong.

Don't use a GUI just because the first ten minutes of Mermaid feel like typing. The first ten minutes of a drawing tool feel like progress, and the file you save is often the last editable copy. I've inherited those files. The person who drew them had left, and the only change requested was a label.

When the text wins the review

Text wins when someone can comment on a line. gate -->|No| auto is a line a reviewer can quote. A screenshot of a green box is a feeling. I want the line in the pull request, next to the code that implements the branch, so a mismatch is obvious.

Text wins when the diagram will change more than twice. The second change is still easy in a GUI. The twelfth change is where the arrows have been nudged so many times that moving one box covers a label. A graph layout redraws. You lose the nudge, and you also lose the broken nudge, which is the point.

Text wins when more than one person edits. Not because live co-editing is the feature to chase. I don't rely on that here, and I'm not describing a multiplayer canvas. It wins because a diff is a sentence. "You flipped the yes and no labels" is a review comment I can write in thirty seconds if the labels are text. On a picture, I draw a red circle and hope.

I still look at the preview before I push. A legal file can say the wrong thing. The preview is how I notice that both arrows landed on the same node because I reused an id. The diff won't shout about that. The picture will, if you look.

The blank page, and a short AI budget

The failure mode I actually have is not syntax. It's the empty file. I know I need a flowchart and I don't want to invent the first four nodes out of politeness. That's when I use the AI.

The AI diagram generator can generate a first draft, edit a diagram you already have, or try to fix a broken one. You get five free AI uses in total, not five a day. I spend them on blank pages and on repairs, not on "make it nicer." Nicer is a word the model can't see, and it will add boxes you then have to delete. Deleting is fine. Spending the last free use on a theme is not.

A prompt that works names the type, the nodes, and the decision. "Flowchart, top down. Nodes: request, limit check, auto approve, reviewer, reject. If under the limit, auto approve. If not, reviewer. Don't add Slack." The guide to writing prompts for the AI diagram generator is the longer version of that discipline. The notes on a prompt that becomes Mermaid are the version with the failure modes written out. Read those before you burn uses on adjectives.

After the draft lands, I edit by hand. I rename ids. I quote labels that grew parentheses. I delete the extra system the model added because "refund" made it think of email. The preview is how I check the edit. The AI is not in the loop for every label. If it is, you'll use the five tries on wording you could have typed.

Fix is the mode I trust most, and I still read the result. A fix that makes the file parse by deleting the branch you cared about is a successful parse and a failed diagram. I've accepted that once. The preview looked clean. The policy was gone. Look at the diff the AI produced the same way you look at a junior's diff. Politely, and completely.

A map of the ways I edit

When I'm choosing how to change a diagram, I don't want another flowchart. I want the choices named, so I stop pretending they're one choice. A mind map is the right shape for that, because nothing here is an order. It's a set of branches off one question.

mindmap
  root((Edit a diagram))
    Text
      Rename a label
      Retarget an arrow
      Quote a punctuation mark
    Preview
      Confirm the parse
      Read the branch labels
    AI
      Draft from a blank page
      Repair a broken line
    Leave it
      GUI for a poster
      Prose if there is no branch

The root is the job, not a step. Text, preview, AI, and "leave it" are siblings. I don't do them in a circle. I start in text if I know the sentence. I start in AI if I don't. I look at the preview either way. I leave Mermaid when the picture isn't a graph.

If someone turns this map into a process chart, they've misunderstood it. "Rename a label" is not step one of a methodology. It's one thing you might do. Mind maps invite people to invent an order. Don't. If the order matters, write a flowchart, and accept that you are now claiming a sequence.

A small chart I would rather type

This is the kind of picture I start in text, because I already know the policy. A drafted AI version would probably add a notification service. I don't want one.

flowchart TD
    start([Issue opened]) --> triage[Triage the report]
    triage --> gate{Security relevant?}
    gate -->|Yes| priv[Move to the private tracker]
    gate -->|No| backlog[Leave it on the public board]
    priv --> owner[Name an owner]
    backlog --> owner

Six nodes, one question, both branches meet at an owner. I can review that in a diff without a legend. priv and backlog are ids. The labels can change when the tracker name changes, and the arrows stay. That's the edit I want a visual editor to make easy: change words, see the box, keep the structure.

If I hadn't known the nodes, I would have asked the AI for exactly these and no others. Then I would have typed the fix if it drifted. Starting in text saved a use. Starting from a blank page with a shrug would have spent one and still left me typing.

Templates sit in the same drawer. The template library is a pile of starter files, not a tour. Open one when the shape is right and the nouns are wrong. Replace the nouns. Delete the branches that aren't your product. A template you extend forever becomes a second product you didn't mean to document.

Comments I leave on diagram diffs

These are the review notes I paste more than once. They're opinions. The parser will not enforce them.

1. Don't ask the author to drag a node "up a bit." Say which edge is missing a label, or which id is doing two jobs.
2. If the AI draft added a system, name the system and ask for it to be removed. "LGTM" on a diagram that invented a queue is how the queue becomes real in a later design.
3. Reject a PNG-only change. The visual editor's output that matters is the text. The PNG is a convenience for a tool that can't read the fence.
4. If both branches of a diamond land on the same next step, ask whether the diamond is real. Sometimes it is, because the side effects differ and the join is honest. Sometimes the author was afraid of a dead end. A dead end is allowed. stop([Stop]) is a fine node. A fake join is worse.
5. Don't request a color pass in the same review as a logic pass. Color hides in the diff and eats the attention the branch labels needed.

A sixth, because it keeps happening. Someone pastes a screenshot of the preview into the PR and doesn't include the source. The screenshot is not reviewable next month. Ask for the fence. If they made the picture in another tool and only want to embed it, that's a different decision, and it should be labeled as an image, not as Mermaid.

The free online diagram tool notes cover the "I don't want to install anything" path. The diagram tool that stays free to open is the cost conversation, which I'm not going to repeat as a pricing page. The editor is free to open. AI uses are capped. Exports of some formats cost money. None of that changes the editing model. You still type, you still look, you still commit the text.

If the blank page is where you're stuck, open the AI diagram generator, spend one use on a named list of nodes, and then edit the text by hand until the preview matches the sentence you can say out loud.