I'm looking for a practical way to keep diagrams maintainable in Markdown documentation that is frequently created or updated with help from language models. Mermaid seems like the obvious choice because it is text-based and renders automatically, but its default diagrams often look unattractive, with awkward layouts and poorly routed lines. I'm wondering whether there are ways to improve Mermaid's output or better alternatives.
I've also considered the Python diagrams library. It produces appealing results, but the diagrams are defined through fairly substantial Python code rather than a compact, dedicated diagram language. That makes it feel less elegant for an LLM-driven workflow where the source should be easy to regenerate and edit.
Schematex looks promising because it has a proper definition language and tooling integrations, although I haven't yet built a workflow around it. I'm also curious whether defining diagrams directly as raw SVG is sensible, or whether that becomes too difficult to maintain.
What tools or strategies are people using for diagrams in LLM-assisted documentation? My current use case is mostly design material and proposals, so absolute technical accuracy is not always essential, but I would still like diagrams that are readable, consistent, and easy to revise.
6 Answers
Before abandoning Mermaid, it’s worth customizing it. Theme variables, hand-drawn styling, and different edge-curve settings can make the output substantially better than the defaults. Rendering locally with the Mermaid CLI also lets you iterate on the appearance while keeping both the editable source and generated image in the documentation repository.
The text source is especially valuable for LLM workflows: a model can read and modify it in context, whereas raw SVG or exported images are much harder to understand and maintain. I’d keep SVG as a generated artifact rather than the canonical source.
For an LLM-assisted workflow, I’d prioritize a deterministic, text-based format over visual polish. The model can inspect and edit the source, and the diagram can be regenerated consistently. The tradeoff is that automatic layouts can still produce confusing routing and unintelligible results, so some manual cleanup may be necessary.
PlantUML is another solid text-based option. It has a large ecosystem of sprites and styling options, so diagrams can look more recognizable than basic Mermaid output while remaining easy to store and regenerate as text. If you need a full visual modeling environment and don’t mind paying for it, Visual Paradigm is considerably more powerful.
D2 does look like a promising balance of quality and interoperability. I’m still exploring whether it works best directly or through an MCP-based workflow.
D2 is worth investigating. It seems to offer a good middle ground between a readable definition language, useful visual output, and interoperability with other tools. It may be a better fit than Mermaid if the default styling and layout quality are important.
Automatically generated architecture diagrams often look rough compared with diagrams made by hand. Draw.io is still a good option when presentation quality matters, although an automated workflow would be much more convenient if it could consistently reach that level of polish.
Related Questions
XML Signature Verifier
Voltage Divider Calculator
SSL Certificate Decoder
SQL Formatter
Online Font Playground to Test Google or Custom Fonts
File Hash Generator Online – Get Instant MD5 and SHA-256 Hashes