AI Diagrams: Chat-Generated, Fully Editable

A common frustration with diagrams is that they fall out of date as a project evolves. Mermaid, a JavaScript-based diagramming and charting tool, was built to address exactly that problem. According to its documentation at https://mermaid.js.org/intro/, the tool “lets you create diagrams and visualizations using text and code,” with a stated goal of helping documentation catch up with development.

This text-first approach is what makes diagrams a natural fit for AI assistants. Because a diagram is defined as plain text rather than as positioned shapes, a language model can produce a valid diagram definition the same way it produces any other code, and a person can then edit that text directly.

How Text Becomes a Diagram

Mermaid renders Markdown-inspired text definitions to create and modify diagrams dynamically. The syntax is intentionally close to Markdown, and the documentation notes that anyone already comfortable with Markdown should have little trouble learning it. This lowers the barrier for non-programmers, who can author diagrams through the Mermaid Live Editor rather than writing code in a project.

When Mermaid is deployed through its API, the parser looks for HTML elements with the class mermaid, reads the diagram definitions inside them, and renders them into SVG. The definition is the source of truth, so editing the diagram means editing the text.

graph TD
    A[Text definition] --> B[Mermaid parser]
    B --> C[Rendered SVG diagram]

Because the output is generated from text, revisions are straightforward: change a node label or add a connection in the definition, and the rendered diagram updates accordingly.

What It Can Represent

Mermaid supports a broad set of diagram types. Its introduction highlights flowcharts, sequence diagrams, Gantt diagrams, class diagrams, Git graphs, entity relationship diagrams (described as experimental), user journey diagrams, quadrant charts, and XY charts. The wider documentation lists many more, including state diagrams, pie charts, mindmaps, timelines, C4 diagrams, and architecture diagrams, among others.

For situations where executing user-supplied content is a concern, Mermaid offers a security level that renders diagrams inside a sandboxed iframe to prevent JavaScript from running. The tool was created by Knut Sveidqvist for easier documentation, and it received a JS Open Source Award in 2019.

Rendering Across Many Formats

Mermaid is one of several text-based diagram formats, and tooling exists to render them in a consistent way. Kroki, a free and open-source service, “creates diagrams from textual descriptions” and exposes a single HTTP API across many libraries, so the same workflow can target different formats. According to its site, Kroki supports formats including Mermaid, PlantUML, GraphViz, D2, and C4 (via PlantUML), with output options such as PNG, SVG, JPEG, and PDF depending on the diagram type.

The Kroki API handles both GET and POST requests. With GET, the diagram is encoded into the URL using a deflate plus base64 scheme that is lossless and can be decoded back to the original source. With POST, no encoding is needed: the diagram can be sent as JSON, specifying diagram_source, diagram_type, and output_format, or as plain text with the output format set through the Accept header.

Why the Text-First Model Fits AI

The pairing of AI assistants and text-based diagram formats works because both sides speak the same language. A model can emit a Mermaid definition, and that definition remains fully editable text afterward, which means a generated diagram is a starting point rather than a fixed image. Storing diagrams as text also lets teams keep them alongside code and documentation, so the visuals can be revised with the same tools used for the rest of a project.