Automating technical diagrams with LLMs: pro workflow with Mermaid, PlantUML and CI/CD

Creating a technical diagram manually takes time. Choosing the right symbols, keeping visual consistency, and maintaining updates quickly become tedious tasks.
Thanks to LLMs (Large Language Models) like ChatGPT, Claude, or Gemini, it’s now possible to automate the generation and maintenance of technical diagrams using open source tools such as Mermaid or PlantUML.

This guide targets developers, architects, and technical writers who want to build a professional CI/CD workflow for maintaining up-to-date, version-controlled, and automatically validated diagrams inside their documentation pipelines.

---

From manual creation to full automation

In the previous article — Create technical diagrams with AI: the simple beginner’s guide — we learned how to generate a diagram from a structured prompt.
Now, we move to the industrialization phase: automating the generation, rendering, and continuous update of diagrams using AI.

The goal is simple:

Turn your diagrams into versioned artifacts integrated into your technical documentation or deployment pipelines.

---

1. Automatic diagram generation pipeline

A professional Docs-as-Code workflow relies on five main steps:

1. Input – textual description, source code, or Markdown documentation.
2. AI processing – the LLM generates Mermaid, PlantUML, or Draw.io XML code.
3. Rendering – automatic conversion into SVG or PNG via CLI.
4. Validation – syntax and logical verification.
5. Publication – continuous integration (Docs-as-Code, GitHub Pages, Notion…).

This model, recommended by DiagrammingAI.com and Eraser.io, ensures reproducibility and visual consistency across collaborative environments.

---

2. Practical example: Mermaid pipeline inside a CI/CD workflow

Let’s take a concrete example using Mermaid CLI, which automatically converts Mermaid code into vector graphics.

Step 1 — AI generation

An LLM receives a structured prompt:

“Create a Mermaid diagram showing a CI/CD workflow for a web project: Commit → Build → Test → Deploy.”

The model outputs a ci_cd.mmd file.

Step 2 — Automatic conversion

In your pipeline (GitHub Actions, GitLab CI, or Jenkins), add:

# Automatic conversion from Mermaid code to SVG
npx @mermaid-js/mermaid-cli -i ci_cd.mmd -o ci_cd.svg

Step 3 — Documentation integration

The SVG is automatically committed and added to the Markdown documentation.
Each change in the prompt or source file triggers an instant diagram update.

This is the principle behind diagram-as-code, popularized by ByteByteGo: the diagram becomes part of your source code.

---

3. Integration with documentation tools

Automation goes beyond command-line usage.
Most documentation platforms natively support Mermaid or PlantUML.

Obsidian, Notion, GitHub

Just insert the code in a block:

```mermaid
graph TD
A[Dev] --> B[CI/CD Pipeline]
B --> C[Production]
```

Mermaid automatically renders the diagram, ideal for design notes or internal technical documentation.

VS Code

Install Markdown Preview Mermaid Support or PlantUML Preview.
You can even define a custom command:

{
  "command": "openai.generateDiagram",
  "args": {
    "promptFile": "diagram.prompt",
    "outputFile": "diagram.mmd"
  }
}

This configuration allows ChatGPT or Claude to write the diagram code directly into your repository.

Docs-as-Code (MkDocs, Docusaurus)

These frameworks already support Mermaid.
A simple plugin renders all diagrams automatically at site build time.
This method is used by AddJam.com to document software architectures efficiently.

---

4. Technical comparison: Mermaid, PlantUML and D2Lang

Format	Syntax type	Strengths	Limitations	Use cases
Mermaid	Markdown-like	Simple, intuitive, web-friendly	Limited customization	Agile docs, blogs, lightweight docs
PlantUML	UML-based language	Comprehensive, precise, flexible	Steeper learning curve	Complex architectures, engineering
D2Lang	YAML-like	Fast syntax, built-in CLI	Less LLM support	Simple infra, lightweight systems

According to PlantUML.cn (2024), Mermaid is better suited for agile documentation, while PlantUML remains the enterprise standard for system and software architecture.

---

5. Quality control and validation

Even the best LLMs can generate invalid code.
A proper validation system is essential.

Syntax checking

• Mermaid linter: npm install -g mermaid-linter
• PlantUML CLI: verifies UML blocks before rendering.

Semantic checking

Python or Node.js scripts can check for required elements:

if "graph" not in diagram_code:
    raise ValueError("Incomplete diagram")

Human review

Final validation should always involve a human reviewer,
an architect or developer who understands the system logic.

This step ensures the diagram accurately reflects the documented system.

---

6. Security and confidentiality

Automation must not expose sensitive information.
Follow these precautions:

• Never send secrets (tokens, IPs, credentials) in prompts.
• Use local AI models (via Ollama or LM Studio) for confidential diagrams.
• Prefer open source tools like Mermaid CLI or local PlantUML.
• Avoid SaaS APIs for infrastructure-related diagrams.

DataScienceCentral reminds that a system architecture diagram is often as sensitive as source code itself.

---

7. Automating documentation with CI/CD

Automation fits naturally into any CI/CD pipeline.
Here’s an example using Makefile and Mermaid CLI:

# Auto convert .mmd files to .svg
%.svg: %.mmd
	npx @mermaid-js/mermaid-cli -i $< -o $@

Each commit on a .mmd file automatically regenerates the corresponding .svg.
The image is then included in the HTML documentation (MkDocs, Docusaurus, GitHub Pages…).

This embodies the Docs-as-Code philosophy: documentation becomes a versioned deliverable, just like code.

---

8. Hybrid generation: AI + manual editing

For complex diagrams (multi-cloud systems, neural networks, AI pipelines), a hybrid approach remains the most efficient.

1. AI phase: LLM generates a skeleton using Mermaid or PlantUML.
2. Manual phase: refine using Draw.io, Figma, or Eraser.io.
3. Final step: export as SVG/PDF and integrate into documentation.

This approach combines AI productivity with human accuracy.
According to Lucidchart AI (2025), hybrid teams save up to 40% of time on architecture documentation.

---

9. ASCII → SVG conversion for lightweight environments

Some environments (GitHub README, CI terminals) require text-based diagrams.
Two main tools can handle this:

• aasvg (official GitHub) aasvg < schema.txt > schema.svg → Converts ASCII art into clean vector SVG.
• Svgbob (online editor)
  → Provides browser-based rendering.

These tools are perfect for minimal, offline-friendly documentation.

---

10. Professional best practices

To maintain a reliable documentation workflow:

• Always store your prompts in the repo (diagram.prompt).
• Version control the generated code (diagram.mmd, diagram.puml).
• Automate rendering through CI/CD.
• Validate logic before publishing.
• Export only in SVG for scalable, high-quality visuals.

According to Mermaid AI Blog (2025), a good automated diagram relies on three pillars: clear prompt, stable pipeline, and human review.

---

11. Generating diagrams from source code

Modern LLMs can analyze code and automatically create diagrams.

Examples:

• Python/Java classes → UML class diagram.
• Docker Compose files → cloud architecture diagram.
• CI/CD logs → execution flow diagram.

Tools such as Microsoft GenAIScript and PlantUML AI are exploring this direction, where documentation regenerates itself automatically at each build.

---

12. Current limitations

Despite rapid progress, full automation still has limits:

• Layout positioning can be inaccurate.
• Some LLMs produce invalid Mermaid syntax.
• Dense diagrams still require manual adjustments.
• Visual consistency varies between models.

Research in diagram reasoning and LLM visual planning aims to address these issues.

---

13. Optimal workflow summary

Step	Action	Recommended tool
1	Write a structured prompt	ChatGPT / Claude
2	Generate diagram code (Mermaid, PlantUML)	LLM
3	Validate and iterate	LLM + human review
4	Render diagram (SVG/PDF)	Mermaid CLI / PlantUML CLI
5	Integrate into documentation	Markdown / Docs-as-Code
6	Version control and automate	Git / CI/CD

This pipeline ensures speed, reliability, and consistency across your entire documentation lifecycle.

---

14. Conclusion

LLMs are no longer just writing assistants, they are becoming true technical documentation agents.
By combining them with tools like Mermaid and PlantUML, you can generate, validate, and maintain technical diagrams automatically while preserving quality and traceability.

This approach embodies the Docs-as-Code philosophy: documentation becomes a versioned, automated production artifact, just like your source code.

If you’re curious about this concept, start with the basics:
👉 Create technical diagrams with AI: the simple beginner’s guide with ChatGPT and Claude