Draw.io mermaid support: what it is, and when to leave

draw.io mermaid support is a bridge, not a home. diagrams.net, which is the name on the current product and the name people still replace with draw.io in conversation, has offered a way to insert Mermaid in recent builds. You paste text, it becomes shapes, and you can drag them. That is useful the day a picture has to sit on a poster. It is a bad place to keep the source if you still want the same words next month. Check Insert in the version you have. I am not going to promise a submenu, and I am not going to promise that editing the shapes writes the same text back.

What support actually means

Support, in the builds that have it, means diagrams.net can take a Mermaid snippet and turn it into a drawing. The drawing is then a diagrams.net file. Boxes have coordinates. Connectors have waypoints. The original lines of text may be stored somewhere in that file, and they may not survive the next edit you make with the mouse. I don't plan on a perfect round-trip. If I need the text, I keep the text in git. The diagrams.net file is a derived picture, the way a PNG is a derived picture, except that it still looks editable, which is the dangerous part.

People hear "support" and expect the app to be a Mermaid editor. It isn't, not in the sense of a preview that updates while you edit the fence and a diff that shows one arrow changed. It is a canvas that can import a starting point. After the import, the canvas features are the product: manual alignment, icon libraries, a page size, layers. Those are real reasons to be there. They are not reasons to throw away the source.

The comparison of Mermaid and draw.io is the longer argument about maintenance. This post is specifically the support question: how the insert behaves as a workflow, and when I stop using it. If you are converting an old drawing the other direction, from a canvas file toward text, the conversion guide is the one to follow. Importing Mermaid into diagrams.net and converting a diagrams.net file to Mermaid are opposite jobs. Doing both in a loop is how you lose a label.

I also won't describe Lucidchart's export buttons here. A neighboring writeup, Lucidchart export to Mermaid, is the place for that product. Visio has the same "we already drew it" problem, covered from the flowchart side in Visio flowchart maker. The habit is shared. The menus are not. Check the version you are staring at.

Check Insert, then stop guessing

Recent diagrams.net builds have put Mermaid under Insert. Yours might say Insert, or a plus menu, or an "advanced" item, or something the next release will rename. Open Insert. If you see Mermaid, that is the path. If you don't, don't hunt through five blog posts from different years. Your build doesn't offer it, or it offers it somewhere I should not pretend to know. Update, or paste the text into a real Mermaid preview and export a picture you can drop on the canvas as an image.

When the menu item exists, paste a small diagram first. A five-node flowchart. Not the 80-node architecture poster. The small one tells you whether the import understands the keyword you used. Flowcharts and sequences are the ones I trust enough to try. A brand-new Mermaid diagram type may import as an error or as a blank, depending on how new it is and how old the build is. If the five-node flowchart imports and your block diagram doesn't, you have learned something about the build. You have not learned that your block syntax is wrong. Check that syntax in a Mermaid renderer before you rewrite it to satisfy an importer.

After the shapes appear, look at one label and one arrow before you start aligning. Importers drop a character, truncate a long label, or turn a decision diamond into a rectangle. If the diamond became a rectangle, the meaning changed, not just the style. Fix it while you still remember which box was the question. A rectangle that says "Over 50 dollars?" is a step that looks like a decision. Readers will treat it as work instead of a branch.

I save the diagrams.net file only after I have saved the Mermaid file. Order matters. If the import fails halfway, I still have the text. If I "improve" the shapes and the tab crashes, I still have the text. The canvas file is the optional artifact.

A flowchart before it is tidy

This is the kind of rough chart I see pasted into an importer because someone sketched it in a hurry. The nodes are vague, the diamond's edges aren't labeled, and "Done box" is doing too much work. It will import. It will also look like a process. It isn't one yet. Moving the boxes around on a canvas will not give the edges names.

flowchart TD
    start[Start] --> work[Do the refund]
    work --> gate{Ok?}
    gate --> left[Thing]
    gate --> right[Other]
    left --> doneBox[Done box]
    right --> doneBox

Ok? is not a policy. Thing and Other are not steps. I am showing this on purpose, because this is the file people import and then spend an hour aligning. Alignment cannot rescue a missing noun. If you are going to use diagrams.net's Mermaid insert, insert a chart you would already merge. Otherwise you will polish a mess and feel productive.

The ids are still real Mermaid. doneBox is the id because I won't use end. Even in a rough sketch, end is the subgraph closer, and an importer that is picky will fail the whole block for a reason you won't see once the shapes are disconnected. Keep ids boring and legal. Put the sloppy words in the labels, where a review can see them.

The same flow once the words are true

Here is the chart I would actually insert, or, more often, the chart I would not insert at all because the text is the deliverable. A refund under fifty dollars is automatic. A larger one waits for a manager. A rejection sends a reason. The automatic path and the approved path both pay. The labels on the diamond are the policy.

flowchart TD
    req[Refund request] --> amount{Over 50 dollars?}
    amount -->|No| auto[Auto approve]
    amount -->|Yes| mgr[Manager review]
    mgr -->|Approved| pay[Send refund]
    mgr -->|Rejected| reason[Email the reason]
    auto --> pay

If you insert this into diagrams.net, you get shapes you can place on a slide with a logo and a footer. That is a legitimate use. The slide is a designed page. Mermaid will not put your logo in the corner, and I don't want it to. Do the insert, align the boxes, export the slide, and leave the Mermaid file untouched in the repo. The next policy change edits the text, and you re-insert, or you accept that the slide is a snapshot and mark it with a date.

What I don't do is insert, drag the rejection box to a nicer spot, change the label to "Notify finance" because it fit the slide, and then treat the canvas as the new source. The repo still says "Email the reason." The slide says something else. Next quarter's argument is about which one the support team memorized. Pick the text. Let the slide go stale, or rebuild the slide from the text. Don't maintain both as if they were the same file.

The flowchart syntax page is the reference for the diamond and the edge labels if the import mangles them and you need to know what you meant. The flowchart online tool post is a different workflow: editing the chart as text in the browser, not importing it onto a canvas. Use that when the tidy version above is the thing you want to keep editing. Use diagrams.net when the slide is the thing.

Round-trip is the disappointing part

I want to be dull about this. You should not expect to open the diagrams.net file next week, change a shape, and get back the same Mermaid with one line edited. Some builds keep the original source in the file's metadata. Editing a shape may leave that source stale, or clear it, or update it in a way that renames your ids. I have seen enough variation that "check your version" is the honest instruction. Do a trial on a copy. Change one label. See whether you can still extract the text you started with. If you can't, you have your answer for that build. Keep the text outside.

Even a perfect extractor would not save the layout work. Mermaid doesn't store the pixel you dragged to. A round-trip that returns text will lay the picture out again with Mermaid's engine. The careful alignment is gone. That is not a bug in the extractor. It is the difference between the two formats. If the alignment was the work, the canvas file is the source and the Mermaid was only a seed. If the words were the work, the Mermaid is the source and the canvas was only a seed. Decide which work you did. Then delete the other file from the "source of truth" list, or mark it generated.

XML is the other temptation. diagrams.net files are XML, and they diff like XML, which means a moved box changes a pile of coordinates. I don't review that diff for a policy change. I review a three-line Mermaid diff. If your team has a reason to live in the XML, the diagram tool free roundup talks about canvas tools and text tools as categories, without pretending one of them won. This post's opinion is narrower: once Mermaid support has been used as an importer, don't confuse the import with ownership.

When the canvas should keep the file

Keep the diagrams.net file as the source when the picture is a designed artifact. A conference poster, a printed one-page architecture with a partner's logo, a network sketch that has to avoid a legend in the corner, a diagram that uses a specific device shape from a library Mermaid does not have. You will spend an hour on spacing. That hour should not be thrown away by a reflow the next time someone adds a node.

In that mode, Mermaid support is a head start. Insert the rough structure, then do the work the canvas is good at. Expect to retype a label. Expect a diamond to need a real decision shape from the palette. Expect the text you pasted to be a starting point you will diverge from. Write the date and the source filename on the page so a later editor knows the Mermaid file may have moved on.

Also keep the canvas when the reader is not going to open a Markdown preview. A customer PDF is a customer PDF. Asking them to render a fence is rude. Export from diagrams.net, or export an SVG from a Mermaid tool and place that SVG. Both are reasonable. The SVG export path is the one I use when the diagram is still text and the customer needs a sharp picture. SVG from this site is a Pro export. I am not going to claim diagrams.net's export dialog matches it. Check that version too. If their SVG looks right, ship theirs.

When the text should keep the file

Keep the Mermaid file as the source when the next edit is "add a step" or "rename the rejection." Those edits are a line. They belong in the same pull request as the code or the policy doc. A canvas file in that pull request will show coordinate noise, and reviewers will skip it. Then the picture and the policy diverge, which is the failure mode this whole conversation is about.

Keep the text when more than one person maintains the diagram. A canvas file has a social rule: the person who drew it is the person allowed to touch it. Everyone else pastes screenshots into comments. A text file has a different social rule: if you can edit Markdown, you can edit the picture. I want the second rule for refund policies and request paths. I want the first rule for posters. Most of the diagrams in our repo are policies.

Don't keep both as editable sources. If you must keep both, generate one from the other in one direction only, and document the direction at the top of the file. "Generated from docs/refund.md. Do not edit shapes." is a sentence that has saved me. The sentence is easy to ignore, so the real protection is not putting the generated file in the place people edit. Put it in an export folder. Put the Mermaid next to the prose.

If Insert isn't in your build, nothing in the Mermaid workflow requires it. You can stay in text. The canvas is optional. The support is a convenience for the day the poster is real, not a dependency for the day the policy changes.

Open the tidy refund chart in the editor and get the words right before you look for Insert. An importer will faithfully turn a vague diamond into a vague shape. It will not name the edges for you. The names are the support that matters, and they live in the text.