Why markdown diagrams beat generated slop every time

7 min read1 hour ago

–

Press enter or click to view image in full size

This is all you need (most of the time, that is)

The slop problem

There’s a word for what AI image generators produce when you ask them to make a diagram. It’s called slop.

Wikipedia now has an article defining AI slop as “digital content made with generative artificial intelligence that is lacking in effort, quality, or meaning, and produced in high volume.” The term emerged from the same cultural exhaustion that gave us “spam” and “clickbait.” We needed a word for the flood of AI-generated images polluting our feeds, and we found one.

Your architecture diagram made with Nano Banana Pro? Slop.

That mind map NotebookLM generated from your meeting notes? Also slop.

The flowchart Napkin.ai produced in under ten seconds? You guessed it.

Slop!

Press enter or click to view image in full size

Slop.

I’m not saying these tools can’t produce attractive images. They absolutely can. The problem is that attractive isn’t the same as useful.

What the tools promise

The pitch is hard to resist. Describe what you want in plain English, and an AI will generate a polished diagram instantly. No learning curve. No fiddling with boxes and arrows. Just type and receive.

Gemini’s Nano Banana Pro, released in November 2025, generates images from text prompts with impressive visual fidelity. NotebookLM added mind map generation in March 2025, promising to turn your research into visual summaries.

Napkin.ai converts text to graphics in under ten seconds, targeting people who want diagrams without the effort of making them.

The marketing works. These tools feel like magic the first time you use them. Then you try to actually use the output and you’ve hit a brick wall.

Why they fail

Here’s the thing about AI-generated diagrams: they’re images. Static, uneditable images.

Max Woolf, a data scientist who’s written a lot about AI image generation, put it bluntly in December 2025: “It takes more effort than usual for an AI generated image to double-check everything in the image to ensure it’s factually correct. And if it isn’t correct, it can’t be trivially touched up in a photo editing app to fix those errors as it requires another complete generation to maybe correctly fix the errors.”

That “maybe” is doing a lot of work. You can’t just fix the one box that’s wrong. You regenerate the entire thing and hope the AI doesn’t break something else in the process.

The version control problem

Your codebase lives in Git. Your documentation lives in Git. Your AI-generated diagram lives… in a PNG file that produces meaningless diffs.

When someone changes the architecture, what happens? You regenerate the diagram. The Git history shows a binary blob changed. Good luck figuring out what actually changed six months from now.

The editability problem

Your colleague spots an error. In a text-based diagram, they open a pull request, change one line, and you’re done. In an AI-generated image, they have to describe the change to you, you regenerate the whole thing, they review it, spot a new error the AI introduced, and the cycle continues.

I’ve watched this happen. It’s painful to say the least.

The visual noise problem

AI image generators love to add visual flourish. Gradients. Drop shadows. Decorative elements. Your simple three-box architecture becomes a visual symphony that takes longer to parse than the text it was supposed to clarify.

You’ve seen the style. Ask an AI to explain a neural network and you get a steampunk contraption with brass gears, Victorian-era valves, tiny people operating levers, and copper pipes connecting everything. It looks like something from a Jules Verne fever dream. Very impressive. Completely useless for understanding how neural networks actually work.

Press enter or click to view image in full size

My eyes, they burn!

The diagram above has gears, springs, sigmoid valves, activation function levers, and workers manning each component. What it doesn’t have is clarity. A simple box diagram with “Input → Hidden Layer → Output” would communicate the same concept in seconds. Instead, you’re squinting at tiny labels wondering what a “bias spring” is supposed to represent. It could have just been:

graph LR    Input --> Hidden Layer --> Output

This is what happens when you optimise for visual impact instead of comprehension.

The AI has learned that elaborate illustrations get engagement. What it hasn’t learned is that documentation exists to transfer knowledge.

The searchability problem

Nobody can grep an image. Your documentation search won’t find that diagram when someone searches for “authentication flow.” The knowledge is locked inside pixels.

The best documentation is the documentation people actually read. AI diagrams optimise for looking impressive, not for being useful.

Why markdown diagrams work

Mermaid has over eight million users. GitHub added native Mermaid support in February 2022. The tool raised $7.5 million in seed funding in March 2024. This isn’t a niche tool for diagram nerds. It’s infrastructure.

Here’s the code:

graph LR    User --> Auth Service    Auth Service --> Database    Auth Service --> Cache

And here’s what a generated Mermaid diagram from that code looks like:

Press enter or click to view image in full size

That’s it. And guess how it got generated.

That’s it. Plain text that renders as a diagram. When someone changes the flow, the diff shows exactly what changed:

User --> Auth Service-    Auth Service --> Database+    Auth Service --> Database+    Auth Service --> Cache

Six months from now, you can read that diff and understand what happened. Try doing that with two PNG files. Good luck on that, and even if you attempted to copy paste the original image on Nano Banana, you won’t get the same exact image as what you spewed in on the first try.

The maintenance argument

Text-based diagrams are reproducible. You can regenerate them from the same source and get the same output. AI-generated images are probabilistic. Run the same prompt twice and you’ll get different results.

When your documentation needs to stay accurate over years, reproducibility matters more than visual polish.

The collaboration argument

Anyone who can edit a Markdown file can edit a Mermaid diagram. The syntax takes about fifteen minutes to learn. Your entire team can contribute without learning a new tool or waiting for someone with “diagram skills” to be available.

The diagram you can edit is infinitely more valuable than the diagram that looks slightly nicer.

AI generated diagrams should be your last resort

Developer trust in AI dropped from 40% to 33% between 2024 and 2025, according to Stack Overflow’s annual survey. The number-one frustration, cited by 66% of respondents, is dealing with “AI solutions that are almost right, but not quite,” which often makes debugging AI-generated output more time-consuming than writing it themselves.

Press enter or click to view image in full size

It’s ironic, isn’t it.

AI-generated diagrams are the visual equivalent of this problem. They’re almost right. The boxes are in roughly the right places. The arrows point in mostly the correct directions. But something’s off, and fixing it means starting over.

The fifteen minutes you saved by not learning Mermaid syntax? You’ll spend it regenerating diagrams that are almost correct. Probably more than once.

What to do instead

Use Mermaid for anything that needs to live in version control. Use PlantUML if you need more diagram types. Use Graphviz if you’re generating diagrams programmatically.

If you absolutely must use an AI diagram tool, treat the output as a starting point, not a finished product. Export it, trace over it in a proper diagramming tool, and throw away the original.

But honestly?** Just learn Mermaid. It takes literally fifteen minutes.** Your future self will thank you when they need to update that architecture diagram and can do it with a one-line change instead of a regeneration lottery.

The goal of documentation is to communicate, not to impress. Choose tools that optimise for the former.

Your AI diagram looks great. But nobody’s going to read it, because nobody can find it, nobody can edit it, and nobody trusts that it’s still accurate.

Press enter or click to view image in full size

Ain’t that fact.

Write it in text. Let the computer draw the boxes.

The terminal-friendly option: ASCII diagrams

Before we end, there’s a question that I need to address: what if you need diagrams in places where images don’t work at all? Terminals. CLI tools. AI chat interfaces. Pull request comments rendered in plain text.

The beautiful-mermaid library solves this. It converts Mermaid syntax directly to ASCII art: no browser, no headless rendering, just pure Node.js:

import { renderMermaidAscii } from 'beautiful-mermaid'const ascii = renderMermaidAscii(`graph LR; User-->Auth Service-->Database`)console.log(ascii)

Output:

┌──────┐     ┌──────────────┐     ┌──────────┐│      │     │              │     │          ││ User │────►│ Auth Service │────►│ Database ││      │     │              │     │          │└──────┘     └──────────────┘     └──────────┘

Need maximum compatibility? Use pure ASCII mode:

const ascii = renderMermaidAscii(`graph LR; A-->B-->C`, { useAscii: true })

Output:

+---+     +---+     +---+|   |     |   |     |   || A |---->| B |---->| C ||   |     |   |     |   |+---+     +---+     +---+

Installation is easy as:

npm install beautiful-mermaid

The library supports flowcharts, sequence diagrams, class diagrams, ER diagrams, and state diagrams. It has over 2K GitHub stars and was built specifically because standard Mermaid.js can’t output ASCII.

You can grep an ASCII diagram. You can paste it in a Slack message. You can include it in a commit message. Try doing that with a PNG.

All the best to your Mermaid journey, Barnacle Boy!

References

• AI slop — Wikipedia article defining the phenomenon
• Mermaid raises $7.5M — TechCrunch, March 2024
• GitHub Mermaid support — GitHub Blog, February 2022
• Stack Overflow Developer Survey 2025 — Source for developer AI trust statistics
• Nano Banana Pro analysis — Max Woolf, December 2025