Ditch Miro: Create AI-Editable Diagrams with Markdown and Mermaid

The Problem with Traditional Diagramming Tools

If you've ever tried to get an AI to modify a diagram in Miro, Lucidchart, or Visio, you know the frustration. These tools store diagrams as binary files or proprietary formats that AI can't read or edit. You end up manually recreating everything based on AI suggestions.

We recently needed to document a sales workflow as an SOP. The natural instinct was to open Miro or draw.io, but that meant:

• Screenshot the diagram, paste to AI, describe what to change
• Manually move boxes around
• Repeat until perfect
• Hope you don't lose the file

There had to be a better way.

The Solution: Mermaid in Markdown

Mermaid is a text-based diagramming language. Instead of dragging boxes, you write simple code that renders as flowcharts, sequence diagrams, entity relationships, and more:

flowchart TD
    A[Customer Visits Website] --> B{Logged In?}
    B -->|Yes| C[Show Personalized Content]
    B -->|No| D[Show Login Prompt]

The magic: AI can read and edit this directly. No screenshots. No copy-paste descriptions. Just say "add a step between B and C for checking subscription status" and Claude rewrites the diagram code.

Our Workflow

We built a simple documentation workflow that combines:

1. VS Code with Mermaid Preview - See diagrams render in real-time as you type
2. GitHub native rendering - Commit your .md files and GitHub displays the diagrams
3. Claude Code for editing - Describe changes in natural language
4. PDF export - High-resolution output for sharing with stakeholders

The entire SOP lives in a single markdown file. Want to change the process? Just tell Claude:

"Add a decision point after the follow-up call to check if they requested samples"

Claude updates the Mermaid code, the preview shows the change instantly, and you're done.

High-Resolution PDF Export

For stakeholders who need printable documents, we use two npm packages:

# Install the tools
npm install -D @mermaid-js/mermaid-cli md-to-pdf

The conversion is a two-step process:

# 1. Render Mermaid diagrams to PNG at 2x scale
npx mmdc -i document.md -o /tmp/converted.md -e png -s 2

# 2. Convert to PDF with custom styling
cd /tmp && npx md-to-pdf converted.md --config-file path/to/config.js

The 2x scale flag (-s 2) produces sharp diagrams that look great when printed or zoomed.

What You Can Create

Mermaid supports far more than flowcharts:

• Sequence diagrams - API interactions, user flows
• Class diagrams - System architecture, data models
• Gantt charts - Project timelines
• State diagrams - Application states, workflows
• Entity relationship diagrams - Database schemas
• Mind maps - Brainstorming, concept mapping
• Git graphs - Branch strategies

All editable with natural language through AI.

Why This Beats Traditional Tools

Traditional Tools	Markdown + Mermaid
Binary/proprietary formats	Plain text
Manual drag-and-drop editing	AI-assisted editing
Separate file from docs	Embedded in documentation
Paid subscriptions	Free and open source
Sync conflicts	Git merge-friendly
Export quality varies	Consistent high-res output

Getting Started

1. Install the VS Code extension: Search for "Mermaid" in extensions
2. Create a markdown file with a mermaid code block
3. Open preview (Cmd+Shift+V) to see your diagram
4. Use AI to iterate: "make the decision nodes yellow" or "add error handling branch"

The learning curve is minimal. If you can write markdown, you can write Mermaid. And if you can describe what you want, AI handles the syntax.

Our SOP Example

We documented our entire wholesale lead flow - from form submission through ongoing customer support - in a single markdown file. The flowchart includes:

• Decision points with conditional styling
• Color-coded stages (blue for start, green for actions, yellow for decisions)
• Retry loops for follow-up attempts
• Clear handoff points between automated and manual steps

When the process changes, we tell Claude what's different, commit the update, and generate a new PDF. No more "which version of the Miro board is current?"

Conclusion

Stop fighting with diagramming tools that weren't built for AI collaboration. Markdown + Mermaid gives you version-controlled, AI-editable, beautifully rendered diagrams without the overhead.

Your documentation should be as easy to update as your code. Now it can be.