I'm looking for a practical way to maintain decent diagrams inside Markdown documentation that is frequently created or updated with help from LLMs. Mermaid seems like the obvious starting point because it is text-based, easy for models to understand, and can render automatically, but its default diagrams often look rough and have poorly routed lines. I've also considered the Python diagrams library, which produces nicer results but requires embedding the diagram definition in Python code. Schematex and D2 look promising because they use dedicated definition languages, and I'm also wondering whether maintaining raw SVG would ever make sense. What tools or workflows are people using to keep diagrams editable, visually presentable, and easy for LLMs to update? These are currently for design proposals rather than precise production documentation, so occasional inaccuracies are acceptable.
4 Answers
For an LLM-assisted workflow, I’d prioritize a deterministic, text-based format over visual polish. Something the model can read, edit, and regenerate reliably is usually more valuable than a beautiful but opaque file.
D2 may be a good middle ground. It has a dedicated syntax, renders more attractively than default Mermaid in many cases, and remains easy to keep under version control. I’d start with the command-line workflow and only add an MCP integration if the basic process works well for you.
D2 was easy to miss, but it does look like a useful combination of visual quality and interoperability. I’m going to explore whether using it directly is enough or whether an MCP wrapper adds anything worthwhile.
For attractive diagrams, I’d still consider creating them manually in a tool such as draw.io and treating the source file as the canonical artifact. Automatic architecture diagrams are convenient, but they often need substantial cleanup before they’re presentation-ready. Raw SVG is usually a poor source format for LLM editing because it is verbose and hard to reason about; it works better as a generated output than as the maintained definition.
Mermaid’s default appearance isn’t necessarily its limit. Themes, custom theme variables, different curve styles, and the hand-drawn look can improve the result. Rendering locally with the Mermaid CLI also lets you keep the text source and generated image together in the repository, which preserves the main advantage for LLM workflows.
PlantUML is another solid text-first option. It has a large ecosystem, supports various diagram types, and can use third-party sprites to make architecture diagrams more recognizable. If you need a full visual modeling environment and don’t mind paying, Visual Paradigm is considerably more capable, though it is less lightweight than a text-based workflow.
That’s fair, but some generated diagrams become difficult to understand when the layout and edge routing are poor. There’s still a minimum visual-quality bar.