Why use ASCII diagrams instead of rendered Mermaid?

Because ASCII survives everywhere plain text goes — code comments, terminal output, commit messages, and log files. Rendered Mermaid only appears where a renderer exists, which excludes most of the places developers actually read code.

Does converting Mermaid to ASCII send my diagram to a server?

Not in the implementation described here. The tool compiles a Go library to WebAssembly and runs entirely in the browser, so the diagram source never leaves your machine.

What diagram types does mermaid-ascii support?

According to its documentation, flowcharts with labeled edges and subgraphs, plus sequence diagrams. It also supports color for diagram elements.

Mermaid to ASCII: Diagrams That Survive Plain Text

July 18, 2026

dev-toolswebassemblydocumentation

Simon Willison published a browser tool that converts Mermaid diagram syntax into ASCII and Unicode box-drawing art. It’s a thin wrapper around AlexanderGrooff/mermaid-ascii, a Go library compiled to WebAssembly so it runs entirely client-side.

The interesting part isn’t the tool. It’s the question it raises: why would anyone want a worse-looking diagram?

Rendered diagrams have a distribution problem

Mermaid is excellent when something renders it. GitHub renders it in Markdown. So do many docs sites and note-taking apps.

The problem is everywhere else. A Mermaid code block is unreadable in:

Code comments
Terminal output and --help text
Commit messages
Log files and error messages
Plain-text email, chat, and issue trackers without Mermaid support
Anywhere someone reads your source in a plain editor

In all of those, a Mermaid block degrades into a wall of syntax the reader has to mentally compile. ASCII art degrades into… a diagram. That’s the entire argument.

The tradeoff is real

ASCII diagrams are genuinely uglier and less capable. You lose curves, precise spacing, arbitrary shapes, and any diagram complex enough that box-drawing characters can’t express it. Nobody should convert an architecture diagram with forty nodes into ASCII and call it an improvement.

The sweet spot is small: a handful of boxes, a clear direction of flow, a few labeled edges. Exactly the kind of diagram that most often ends up in a code comment or a README — and exactly what gets skipped today because embedding a diagram there is inconvenient.

Where this fits in a real workflow

The practical pattern is to keep Mermaid as the source of truth and generate ASCII where plain text is the delivery format:

Mermaid source (in docs, version-controlled)
        │
        ├──► rendered SVG  → docs site, README on GitHub
        │
        └──► ASCII art     → code comments, CLI help, commit messages

That diagram is itself the point — you’re reading it in a Markdown file, in a code block, with no renderer involved.

There’s a second reason this matters more in 2026 than it did a few years ago: plain-text diagrams sit well in an LLM’s context window. When you paste a file into a coding agent, an ASCII diagram in a comment is read as structure. A Mermaid code block is read as syntax the model has to parse before it means anything. If you keep architecture notes in comments for your own agent to read, ASCII is the friendlier format.

We can’t cite a benchmark for that claim — it’s a reasonable inference from how these tools consume text, not a measured result. Treat it as a hypothesis worth testing on your own codebase rather than an established fact.

WebAssembly is quietly the right answer here

The implementation detail worth noting: this is a Go library that was never written for the browser, compiled to WASM and shipped as a static page. No server, no API key, no upload.

That pattern is becoming the default for developer utilities. Anything that’s pure computation over text you already have — formatting, converting, hashing, encoding — has no business making a network round trip. The same reasoning is why our own JSON formatter and Base64 encoder run in your browser instead of on our servers. Your data doesn’t leave the tab, and the tool works offline.

A sibling tool, grok-mermaid, takes the same approach in Rust for Unicode box art. We haven’t tested it, so we can’t compare output quality.

Try it

The live demo is at tools.simonwillison.net/mermaid-ascii, and the underlying library is on GitHub.

Start with a diagram you’ve already got in a README and paste it in. If the ASCII version is readable, it probably belongs in the code too — closer to the thing it describes, where it’ll actually get seen.

Sources: mermaid-ascii and grok-mermaid on Simon Willison’s blog.