From ASCII Art to Mermaid

For the first 12 years of my career, most of my work was using a terminal and vi editor. Many of the design documents were simple text files, or just direclty documented in code. ASCII art was the to draw diagrams, and it was great. Simple illustrations. At one of the startups I worked at, we maintained all our design diagrams in text files—there was no other option. This wasn’t just a preference; it was the reality of working in Unix environments where everything was text-based, version-controlled, and had to work over SSH connections.

I’d spend hours on asciiflow.com, carefully drawing boxes and arrows with text characters,trying to make them look somewhat professional. The results were functional but fragile—one character misaligned and the whole diagram fell apart. Sharing them in markdown files or design docs worked, but editing them was always a pain.

+----------------+      +------------------+
|    Browser     |----->|   Web Server     |
+----------------+      +------------------+
                               |
                               v
                        +-------------+
                        |  Database   |
                        +-------------+

Recently, I discovered Mermaid, and it’s changed how I think about diagrams in documentation. Instead of drawing with characters, you write code that describes the diagram. The syntax is clean, the diagrams look professional, and best of all—they’re easy to edit and version control. Plus, they automatically adapt to light and dark themes on my blog.

Here’s that same diagram in Mermaid:

Let me show you what’s possible with Mermaid.

System Architecture Example

Sequence Diagram Example

Here’s how a typical request flows through the system:

Flowchart Example

Decision flow for publishing content:

Class Diagram Example

For documenting system components:

Git Graph Example

Visualizing branching and merging:

State Diagram Example

Perfect for modeling state machines and workflows:

Entity Relationship Diagram

For documenting database schemas:

Gantt Chart Example

Great for project planning and timelines:

Wide Gantt Chart Example

With AI-powered development, what used to take years now takes weeks. This 90-day sprint shows how horizontal scrolling helps visualize packed timelines:

Pie Chart Example

Useful for showing proportions and distributions:

Quadrant Chart Example

For categorizing items across two dimensions:

How to Use Mermaid

To add any of these diagrams to your markdown files, just use standard code blocks with mermaid as the language:

1
2
3
4
5

```mermaid
graph TD
    A[Start] --> B[Process]
    B --> C[End]
```

The diagrams automatically adjust to match your site’s theme—light or dark mode—which is something ASCII diagrams could never do.

Why I Switched

Here’s what I appreciate about Mermaid over ASCII diagrams:

Version control friendly: Changing a diagram is as simple as editing a line of text. With ASCII art, any structural change meant redrawing half the diagram.

Consistent styling: All diagrams look professional and match each other. No more aligning boxes by hand or counting spaces.

Easy to edit: Want to add a new node? Just add a line. Want to change a relationship? Update the arrow. In ASCII, this meant shifting entire sections around.

Portable: The same Mermaid code works in GitHub, GitLab, Notion, and countless other tools. ASCII diagrams looked different everywhere depending on font rendering.

Maintainable: I can actually come back to a diagram six months later and understand how to update it. ASCII diagrams were write-only code.

For quick sketches, I still use a whiteboard or pen and paper. But for anything that goes into documentation, Mermaid has completely replaced my ASCII diagram workflow.

Resources

If you want to try Mermaid:

• Mermaid Documentation - Complete reference for all diagram types
• Mermaid Live Editor - Interactive playground to test diagrams
• Syntax Guide - Quick syntax reference

The learning curve is minimal—if you can write markdown, you can write Mermaid diagrams.