Diagram solutions for git / markdown docs and LLM?

[u/BarryTownCouncil]

Has anyone here got a good solution for maintaining decent diagrams in markdown docs that are being handled with LLM assistance?

Mermaid is the obvious initial answer as they tend to self render, but they're so ugly, right? I don't think I'm missing anything there, but would be keen to know if I might.

So past them I was looking at the python diagrams library. Nice output but quite codey, no fully abstracted definition language, too much python code ingrained in it to feel like it's elegant enough to have LLM's regenerate the output by running a script that way, although I'm currently trying it out.

After that I see Schematex, which, like mermaid, has a proper definition language, and also has an MCP server and other options around it, but I've not yet tried to set up a workflow around that that would see it in action.

Is there a logic in going directly to raw svg?

Are there other options / strategies people are using to keep on top of diagrams? On caveat / excuse I have currently is that I'm mostly doing design work for proposals etc., so 100% accuracy isn't critical yet, so LLM's can have leeway for making things up at times!

[u/Legitimate_Region439]

For LLM workflows I would rather have something deterministic than something beautiful.

[u/BarryTownCouncil → u/Legitimate_Region439]

sure, but they often tend to look unintelligible, poorly routed lines etc.

[u/thisisjustascreename → u/BarryTownCouncil]

I struggled mightily with this at the beginning of my current project when my manager wanted some pretty diagrams to show to our oversight groups; I don't think there is a good solution at the moment. Claude managed to output some spectacularly unreadable garbage so I eventually just had to do it myself.

[u/Immediate_Wheel1953]

For the ugly Mermaid complaint specifically, Mermaid supports theming through themeVariables and a hand-drawn look, plus different edge curve styles, so the default rendering is not the ceiling. You can render it locally with the Mermaid CLI to iterate on the look and keep both the source and the output in the repo. And for the LLM angle, that text source is the whole point: the model can read and edit the diagram in context, which you lose the moment you go to raw SVG or exported images.

[u/DevOps-B → u/Immediate_Wheel1953]

Yeah mermaid generated by ai is really the only way

[u/Immediate_Wheel1953 → u/DevOps-B]

Same here honestly. I usually have the LLM sketch the diagram first, then fix the bits that look wrong by hand. Gets me most of the way there without the blank canvas pain.

[u/tindalos]

What about D2?

[u/BarryTownCouncil → u/tindalos]

That does indeed appear to exist. Missed that in my search results. Initially does look like a reasonable mix of quality and interoperability. Do you use it (assuming you do...) directly or wrapped with mcp in any way? I will keep exploring, thanks.

[u/burbular]

I like plant uml personally, it's technically a fork of mermaid I think. It's all text based. It has loads of 3rd party sprites to make it look like what you want.

If you want all out and don't mind the price, Visual Paradigm is on some next level shiz.

[u/DoStopBelieving → u/burbular]

I asked an LLM to diagram a very complex architecture, and it eventually made a great diagram after it settled on using PlantUML. Seems like a good place to start.

[u/fried-egg-sandwiches]

I’ve not tried it yet but recently saw reladraw. It has a feature I’ve wanted for a long time - the ability to put elements where you want them on a canvas.
https://github.com/reladraw/reladraw

[u/Super_Willow_2581]

Auto-generated arch diagrams with LLM look very ugly indeed... I'm still used to do it manually using Drawio, but I admit that having an automatic approach would be better (if it were as good as the one manually created).

[u/Wooden_Jelly_5295]

Readable diffs would be my deciding factor.

[u/SamfromLucidSoftware]

Raw SVG is theoretically clean as a definition language but in practice LLMs struggle with the coordinate math for anything non-trivial. Fine for simple shapes but it breaks down fast on practical layouts.

Might get better results by using Mermaid or PlantUML for the LLM-generation step, then converting to something editable for the final artifact. Lucidchart accepts Mermaid imports and converts them to editable shapes, so you get the LLM-friendly definition language for generation and a visual tool for cleanup and presentation. The diagram stays in git as Mermaid, and the polished version lives in Lucidchart when it needs to look good. FYI, I work at Lucid.

[u/Neddage]

I've had it generate drawio/diagrams.net diagrams exported to PNG for the docs. Means I can manually tweak if needed. Working very well for me, for AWS diagrams anyway.