Support Export to Mermaid Markdown Diagrams

[DarwinJS]

Would love to be able to graphically draw and then export to mermaid. https://mermaidjs.github.io/

Version 3 of the functionality would restrict my drawing abilities so that during drawing I can always be assured the result would export to mermaid.

[alderg]

Our of interest: What is the use case of this, ie why not just write the Mermaid markup directly or draw the diagram directly?

[rbarels]

I'm not DarwinJS, but I woudl guess: ease of use while using Draw.io as gui, and exporting the diagrams for documentation in .md files, accepted by the documentation tooling they use.

[davidjgraph]

For a project of the scale that this is, none of the core team are willing to expend several months implementing and supporting this. I'll leave it open and label it help wanted.

[DarwinJS]

Yes, @rbarels has it right. GitLab renders mermaid natively. For the record, I use draw.io and save as SVG as I like the richer capabilities. However, mermaid has no signficant GUI editing tool at this time - so it could be an entry way into showing how draw.io can also product graphics that are git friendly.

[stale[bot]]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.

[DarwinJS]

So I see this is a feature now: https://drawio-app.com/create-mermaid-diagrams-in-draw-io/

Was it developed under a different issue?

[davidjgraph]

This issue is export to Mermaid, we don't have that.

[daraul]

Any plans to add support? I have a few rather large diagrams that I would love to put under version control.

[davidjgraph]

How would this be implemented? The technical details are pretty horrific when you look at them in detail.

[daraul]

The technical details are pretty horrific when you look at them in detail

I don't doubt that; I was just holding out hope it might happen.

How would this be implemented?

The first thing that comes to mind is some kind of DSL that can compile down to mermaid/plantuml.

[davidjgraph]

But how would you restrict drawing to exactly and only that which is possible in mermaid/plant?

[daraul]

I would not even try; instead indicate to the user that their diagram is not compatible with mermaid/plant. Maybe leave the appropriate UI button greyed out, with a note. The user can then edit their diagram accordingly.

The UX of that doesn't sound very attractive, but it can be improved upon in some v2 implementation.

I realize this is already a huge headache, so feel free to ignore me if the team is really against it :laughing:

[davidjgraph]

Maybe the title of the issue is wrong. It sounds more like you want a format that leads itself well to diffing in source control. A more realistic option is to re-format the existing XML and ensure deterministic orders of elements. If yes, I'd suggest a new issue specifying that as the goal (I don't want to change this issue title in case mermaid export support really is the primary goal).

[daraul]

I suppose that can work as a middle-ground. I would still like to see mermaid/plant support, though.

[DarwinJS]

@davidjgraph - rather than trying to guarantee the authoring experience, what about just stripping off anything that mermaid does not support during export?

Point folks to guidance on mermaid "capabilities" and provide 5-10 working examples with at least one uber-example that shows off every mermaid feature (authored in pure draw.io, but export cleanly to mermaid with everything intact).

I think the community could help with the examples - I'd be willing to!

Like Typora for Markdown authoring, I think someone will eventually plug this gap - would love if it was my go-to drawing tool!

[epnaveen]

Fully agree with @DarwinJS. I see the ability to export to Mermaid or PlantUML becoming a necessity in the future.

[davidjgraph]

What's the ETA on this?

[davidjgraph]

I'll close this since nobody seems to be working on it. If you want the feature, please write it and submit the PR. Ensure the functionality is fully tested and security issues have been reviewed.

[davidjgraph]

Mermaid to draw.io model is in 21.0.6. Note that draw.io to mermaid is still not a possibility.

[GuerrillaCoder]

now possible with GPT-4. Export to XML then ask GPT-4 to convert to mermaid. Your mileage may vary but for me if all arrows are locked in properly it works perfectly.

[LouisAmon]

I gave it a try with GPT-4 as well and most of the time the XML code is too big to be copy/pasted in the chat.

Even with a small chunk on a simple flowchart the results were unsatisfactory : GPT-4 was quickly getting confused between nodes and could note produce the correct mermaid code.

(Just sharing my feedback)

[davidjgraph]

GPT-4 performed very poorly when I tested this, also. If you create a diagram limited to something that you know can be represented in mermaid then some basic results are possible, but without UI support for this limitation it's a mess.

Given that it's most likely GPT that will provide some kind of implementation for this, someone could work on it outside of this project (a simple UI that takes our XML and outputs mermaid). Users can provide their own API key to run it.

[GwynethLlewelyn]

One might argue that an alternative to getting Draw.io to export to Mermaid is to get GitHub/GitLab to natively support Draw.io... 😼

[Ant0wan]

I'll close this since nobody seems to be working on it. If you want the feature, please write it and submit the PR. Ensure the functionality is fully tested and security issues have been reviewed.

To @davidjgraph, While I understand the need to prioritize and allocate resources, Drawio has been a valuable tool for documenting our projects, helping us save time and streamline our work. For many of us, documentation may not be the core of our responsibilities, but it plays a crucial role in ensuring clarity and efficiency in our projects. I'm disappointed to hear that the development of this feature isn't currently on the roadmap. It's disheartening to think that we've invested in Drawio primarily for its capability to facilitate smooth documentation processes. From a business perspective, I can appreciate that every feature must be evaluated for its potential impact. However, I wonder if enhancing documentation capabilities might not only benefit us as users but also draw in new customers who value comprehensive documentation tools. Considering alternatives like Mermaid or Graphviz is a valid option, but it's also important to weigh the advantages of sticking with Drawio, a tool we're already familiar with and have invested in. I hope that we can revisit the possibility of including this feature in future development plans, as it could greatly enhance our experience with Drawio and potentially attract more users who prioritize robust documentation capabilities. Thank you for considering my feedback.

[davidjgraph]

Thanks for taking the time to ask chatgpt to write your mesage :D. The problem with chatgpt answers is that they don't actually say anything. Si vous voulez écrire en français parce que vous trouvez l'anglais difficile, ça marche pour moi.

"we've invested in Drawio". You used draw.io with the feature set available at the time. Using a project with a specific feature set then complaining when you don't get a new feature, yeah, you can do that with a commerical project. When you get the project for free the tone isn't quite right...

[Ant0wan]

@davidjgraph Thank you for your unhelpful response, which I must say I found to be rather critical. I will no longer maintain a polite tone. You responded negatively to my request for reconsideration of this feature. It's quite apparent that this feature is necessary if you wish to remain a tool in use. Starting now, we will explore other solutions. Wishing you good luck.

[davidjgraph]

Thanks, it's a shame our tool will fade into obscurity without this feature, it was a good run...

[davidjgraph]

Serious point now folks. Why do you expect us to write a visual editor for mermaid? Why don't you expect the mermaid team to write a visual editor for mermaid? They have a larger development team than us.

draw.io is really badly suited for this, something like tldraw or excalidraw would work better. Have you opened issues on the mermaid, tldraw or excalidraw repos?

[EvoTechMike]

GPT4 is now giving me absolutely perfect conversion of my flow charts to mermaid. Before the XML approach was a bit touch and go but now by exporting to png then uploading the png to gpt4 vision it will give me perfect matching mermaid code.

It may be my flow charts are simplistic enough and follow conventions so it works for me and fails for others but for me it is accurate.

[davidjgraph]

GPT4 is now giving me absolutely perfect conversion of my flow charts to mermaid.

Nice. 4 isn't available on the API as yet. GPT is the only realistic way this could be implemented. I'll re-open and change the title to reflect that.

[DarwinJS]

As the creator of this issue, I would like to say that the renaming of the issue completely changes my ask and intent. Let me explain why I feel a live, as you work, visual editor for one or more of the "Diagrams as Code" DSLs is a business opportunity that will eventually be filled and why draw.io is uniquely suited.

Since many software companies aspire to documentation as code (Markdown, Asciidoc, etc) and "as many things as code as possible due to being storable and manageable in SCM" they tend to use and render some of the standard Diagrams as Code Languages such as Mermaid and PlantUML.

So I committed to a learning journey and attempted to create some specific diagrams in Mermaid. It became hard to create the diagrams I wanted and so I proceeded to learn PlantUML. Like Mermaid, PlantUML had no control over object placement and I ended up in PlantUML C4 specifically where there are attributes that enable relative positioning.

1. the best results of my efforts in plain PlantUML are here: https://gitlab-for-eks.awsworkshop.io/070_architecture_patterns/gitlab-agent-connections.html#architectural-depiction-1

2. The much "closer to my vision" version in PlantUML C4 is here: https://gitlab-for-eks.awsworkshop.io/070_architecture_patterns/gitlab-agent-connections.html#architectural-depiction-2

This second diagram took many hours of playing to get it just right because the original site for it never outlines the order of precedence processing of visual directives and what happens if I "use more of them than necessary" (which becomes natural when your only way to figure it out is doing repetitive, frustrating experiments to discover how something works). Once I felt I understood the rendering engine's priorities, I contributed that knowledge back as documentation here: https://gitlab-for-eks.awsworkshop.io/070_architecture_patterns/gitlab-agent-connections.html#architectural-depiction-2 (the entire section of this heading)

Add to this another experience - I realized that when updating documentation I was avoiding tables in markdown because editing them as source is pure frustration. Until I found Typora - the WYSIWYG markdown editor. It restored the simplicity of a GUI authoring environment for something that is very fussy - but also a relatively occasional skill.

When I showed other colleagues Typora - especially those in non-technical functions - they were ecstatic with stress relief.

I also realized documentation as code companies not only end up with a lack of tables, but also a lack of diagrams. Hence I fell in love with draw.io since both source and result could be stored in SCM.

However, it still does not meet my need for using Diagram as Code for specific activities.

And I think there in lies the challenge. Developers who spend all day building a "Diagram as Code" domain specific language have the curse of expertise or familiarity. They can't see how graphical authoring is a problem that needs solving because "who wouldn't have the opportunity to spend gobs of time learning it through trial and error 'post-coding-rendering' (non-real time)."

And that leads to a second problem - folks who build a "thing" generally envision their users as needing and using the thing daily. So they can default to a "yeah hard to learn, but learn it once and you'll retain it" - which is not actually true of occasional use scenarios. In many roles the need for the skill is much less frequent than the "Developer as Product Manager" conceives of.

It is my opinion and theory that GUIs function as a simplifying mechanism (as described in the book "The Laws of Simplicity") - even for coding developers. None of us (even coders) can maintain the quantum level proficiency of "as-code" for things we use occasionally. GUIs take us over this hump.

Due to the magnitude of the frustration of my journey, combined with my occasional usage pattern and the fact that I had to reverse engineer rending rules to effectively use one of these DSL is what makes me feel there is great opportunity here for "live restrictions" on visual editor whose storage format is a Diagram as Code DSL.

Since Draw.io/diagrams.net is all over the idea of using SCM compatible, text-based storage for visuals (albeit only comprehensible by machine) - I felt it was a good fit, both in terms of existing technology (text based storage) and product vision.

Probably a third problem is that in many technology companies there is a draw toward Diagram as Code DSLs and such companies can tend to put "format rules" above "pragmatic usability" - so stress about usability grows which affects productivity and avoidance of creating visuals - and draw.io relieved me of that stress for the "storable in SCM" requirement - and that is another reason why it felt natural to ask for this here - it could further relieve that stress for this area.

Your increase in asks might be a reflection that the need (aka business demand) side is increasing and your solution is viewed as a natural fit because it already addresses part of the problem.

If it was built as a sort of rules engine that processes immediately after mouse release on an authored or updated segment - I get the immediate feedback on what layout actions are available to me. If it was a rules engine, it might also be able to support multiple Diagram as Code DSLs.

That is the user experience I feel is sadly lacking and is an opportunity .

If I was to change the title and intent of this original issue it would be to "Support Realtime Editing Constraints to What Can be Done in PlantUML C4 (and possibly structurizr)"

[davidjgraph]

Thanks for the clarificiation. I've restored the titled and will close the issue again.

[EvoTechMike]

@DarwinJS why not use https://www.mermaidflow.app/ to build your flow charts?

My use case is we write proposals in draw.io & goggle docs so they look nice for clients but then later I want to re-use that content in project wikis. Embedding an image of the flow chart is annoying because other contributors cant easily edit it so mermaid works way better here. Now that GPT4 vision is released it meets my use case so there is no need to write a parser to get mermaid markup directly from draw.io. The parser would be most accurate way to handle this but a lot of effort to go to when GPT4-V handles it pretty well.

Do you have a specific use case where you need to convert draw.io to mermaid?

[DarwinJS]

@davidjgraph - thank you for restoring the name - I think it will help everyone know that this is not a desired direction for the product.

[DarwinJS]

@EvoTechMike - It looks a LOT like what I'm thinking. However, I'm on to PlantUML C4 now and some I know of are using structurizr. An advantage of structurizr is it supports a "progressive disclosure" presentation mode so you can interactively explain architecture diagrams, but it add just the elements you are about to explain when you "advance" the presentation.

[pravishanth]

In draw.io, selected the diagram, exported to XML and pasted in claude.ai and asked to convert it to mermaid diagram, which it did perfectly, except for a small mistake (the start which was supposed to be circle it gave rectangle). But overall, this works well.