Building MermaidEditor.io: From Side Project to 3,000 Monthly Users in 30 Days
MermaidEditor.io is a free online diagram editor for Mermaid.js — the text-based diagramming syntax that GitHub renders natively in Markdown. I built it because GitHub gives you zero feedback when your Mermaid syntax is wrong: you commit, see a blank gray box, and have no idea what broke.
The editor solves this with live preview, inline error highlighting, 21 diagram types, theme presets, and export to PNG, SVG, and PDF — no login required.
In its first full month (March 2026), MermaidEditor hit 2,922 monthly active users, 25,361 pageviews, and 1,166 diagram exports. But the most surprising metric was where the traffic came from: 25% of all visits were referred by ChatGPT.
This post covers the technical architecture, the hardest engineering problem I solved (the export pipeline), how I integrated AI features, the monetization experiments I ran, and what I learned about building for AI-driven discovery.
The Problem: GitHub's Silent Failure
If you've ever written a Mermaid diagram in a GitHub README, you know the pain. You push a commit, navigate to the rendered Markdown, and see... a gray box. No error message. No line number. No hint at what went wrong.
flowchart TD
A[Write Mermaid in README] --> B{Push to GitHub}
B --> C[See blank gray box]
C --> D[No error message]
D --> E[Guess what's wrong]
E --> A
Every Mermaid user has this workflow burned into muscle memory. The edit-commit-check loop is brutal when you're debugging syntax. I wanted a tool where you paste your code and immediately see what's wrong — with the actual error underlined, not hidden behind a silent render failure.
Architecture Overview
The stack is intentionally modern but pragmatic:
- Framework: Next.js 16 (App Router) with React 19 and TypeScript
- Editor: Monaco Editor with custom Mermaid language support via
monaco-mermaid - Rendering: Mermaid.js 11.x running client-side in the browser
- Styling: Tailwind CSS 4 with shadcn/ui components
- Export: Canvas API (PNG), native SVG serialization, jsPDF (PDF)
- AI: Vercel AI SDK with Anthropic Claude and Google Gemini providers
- Database: Turso (libSQL) via Drizzle ORM for cloud diagram storage
- Auth: Clerk for optional user accounts
- Payments: Stripe for Pro subscriptions
- Analytics: PostHog (server + client) and Vercel Analytics
- Deployment: Vercel with automatic preview deployments
The key architectural decision was making the editor fully functional without authentication. Users can open the site and start diagramming immediately — no signup wall, no "create an account to save" interstitial. Diagrams auto-save to local storage. Accounts are optional and unlock cloud sync.
The Export Pipeline: The Hardest Problem
Exporting a Mermaid diagram to a high-quality PNG, SVG, or PDF sounds straightforward. It isn't.
The core challenge is converting a Mermaid-rendered SVG into a raster image. The pipeline is: SVG → <img> element → <canvas> → file download. The critical step is loading the SVG string into an <img> tag so it can be drawn onto a canvas.
The Approach That Won: Percent-Encoded Data URLs
After testing multiple strategies, I settled on percent-encoded data URLs:
const dataUrl = `data:image/svg+xml;charset=utf-8,${encodeURIComponent(svgString)}`
This handles all Unicode characters (emoji, CJK, mathematical symbols), always fires onload/onerror callbacks, and has no practical size limits. Two other approaches were tested and rejected:
Base64 data URLs failed on non-Latin1 characters — btoa() throws on emoji and CJK text, which is common in diagrams. They also hit browser URL length limits (~2MB) on large diagrams.
Blob URLs (URL.createObjectURL) were worse: they can silently fail in Chrome and Safari. Neither onload nor onerror fires, leaving the export Promise hanging forever. The canvas also gets tainted due to CORS origin mismatch, making toDataURL() throw.
htmlLabels: The Subtle Killer
One of the trickiest bugs was that Mermaid renders node labels as <foreignObject> HTML by default (the htmlLabels: true setting). This looks great in the browser DOM but is invisible when the SVG is loaded into an <img> element — <foreignObject> content doesn't render in that context.
The fix: force htmlLabels: false during export, which tells Mermaid to use native SVG <text> elements instead. The preview still uses HTML labels for better styling, but exports get pure SVG text.
Export Safeguards
Every export includes a 30-second timeout on image loading, error tracking via PostHog (export_failed events with format, diagram type, and error details), and retry logic for transient failures.
The entire export pipeline is covered by Playwright tests that run against a real browser:
- PNG, SVG, and PDF export for 4 diagram sizes
- File validity checks (PNG pixel analysis, SVG structure, PDF header)
- Blankness detection — catching the "export succeeded but produced a white image" failure mode
- Console error monitoring
pnpm test:exports # runs on every PR touching export code
AI Features: Repair Over Generation
I integrated AI in two ways: AI Generate (create a diagram from a natural language prompt) and AI Repair (fix syntax errors in existing code).
The surprising finding from production data: AI Repair is used 5.7x more than AI Generate. In March, users triggered 362 repair requests vs. 63 generation requests. The completion rate for repair was 74%, while generation hit 98%.
This makes intuitive sense once you think about it. Most users arrive with existing Mermaid code that's broken — they pasted it from a ChatGPT response, copied it from documentation, or tweaked syntax that was working before. They don't need AI to create a diagram from scratch; they need AI to tell them why their bracket is in the wrong place.
The AI features use Vercel AI SDK with streaming responses. Repair sends the broken Mermaid code plus the exact error message to Claude, which returns corrected code with an explanation. It's essentially a specialized debugger.
March 2026 AI Usage:
├── AI Repair: 362 requests (74.3% completion)
├── AI Fix All: 133 requests (56.4% completion)
└── AI Generate: 63 requests (98.4% completion)
First Month Metrics
Here's what the PostHog dashboard showed after the first full month of operation:
User Growth
| Metric | Value |
|---|---|
| Monthly Active Users | 2,922 |
| Peak Daily Active Users | 802 |
| Total New Users (5 weeks) | 3,151 |
| Total Pageviews (March) | 25,361 |
| Avg. Session Duration | 3–10 minutes |
Feature Usage
| Metric | Value |
|---|---|
| Diagram Exports (March) | 1,166 |
| Chart Auto-Saves | 18,743 |
| Templates Used | 188 |
| AI Features Triggered | 558 |
Export Format Breakdown
PNG leads at 48%, followed closely by PDF at 43% — which surprised me. I expected PNG to dominate. The high PDF share suggests a significant portion of users are exporting diagrams for documentation, reports, and presentations rather than embedding in web content.
| Format | Share |
|---|---|
| PNG | 47.9% |
| 42.7% | |
| SVG | 8.5% |
| Markdown | 0.9% |
Conversion Funnel
- Editor Loaded: 2,268 users
- Export Completed: 126 users (5.56% conversion)
- Median Time to Export: 1 min 36 sec
- Average Time to Export: 14 min 2 sec
The bifurcation between median and average tells an interesting story. Half the users know exactly what they need — paste code, export, done in 90 seconds. The other half spends significant time crafting and iterating on their diagrams.
The ChatGPT Traffic Story
The most remarkable finding was the traffic source breakdown:
| Source | Share |
|---|---|
| Direct | 34.0% |
| Google Search | 28.6% |
| ChatGPT | 24.8% |
| Bing | 2.7% |
| DuckDuckGo | 2.0% |
| Perplexity AI | 1.1% |
| Gemini | 0.1% |
A quarter of all traffic came from ChatGPT. When you combine all AI sources (ChatGPT, Perplexity, Gemini, Claude), AI chatbots account for roughly 26% of referrals.
This wasn't accidental. I invested in what's now called GEO (Generative Engine Optimization) from day one:
llms.txt— A structured text file at/llms.txtthat tells AI crawlers exactly what the tool does, what diagram types it supports, and how to use itrobots.txtallows all AI crawlers — No blocking of GPTBot, ClaudeBot, or other AI user agents- SEO landing pages per diagram type — 21 pages targeting queries like "mermaid flowchart editor", "mermaid sequence diagram online", each with examples and syntax guides
- Fact-dense, structured content — Instead of marketing prose, the landing pages use concrete claims: "21 diagram types", "PNG/SVG/PDF export", "no login required"
The theory is that LLMs extract and recommend tools based on structured, authoritative content. When someone asks ChatGPT "how do I make a Mermaid flowchart", it recommends tools it has seen described clearly and specifically. Marketing fluff doesn't help — concrete capabilities do.
I wrote about this approach more broadly in the context of GEO optimization for personal sites.
Monetization: A/B Testing the Upgrade Path
MermaidEditor uses a freemium model: the core editor is free forever, and Pro ($7/month or $39 lifetime) removes watermarks, unlocks high-resolution exports (up to 8x / 768 DPI), and adds 200 AI generations per month.
The conversion challenge with developer tools is that the free tier has to be genuinely useful — otherwise nobody sticks around to convert. I ran several A/B tests on the upgrade flow:
Post-Export Modal Variants
The post-export modal appears after every free export with the watermark visible on the diagram. I tested two layouts:
- Split Panel (Default): Shows the exported diagram preview alongside the upgrade pitch. Users can see their watermarked diagram and the value prop side by side.
- Receipt Variant: Treats the export like a receipt — shows format, resolution, watermark status, and a clear comparison of free vs. Pro capabilities.
Upgrade Modal Layouts
I tested three distinct upgrade modal designs:
- Compact Single Card: Focused on a single decision — pick monthly or annual, then checkout. Minimal friction, best for impulse conversions.
- Side-by-Side Comparison: Shows Free vs. Pro feature-by-feature. More information helps justify the price but can feel heavy as a modal.
- Contextual Upgrade Prompt: Tells the user why they're seeing this (e.g., "Watermark-free exports require Pro"). Changes message based on the trigger context.
Export Upgrade Banner Variants
The export toolbar banner is the most visible upgrade surface — it appears every time a free user exports. Three copy strategies:
- Control (Premium Positioning): "Remove watermark & unlock print DPI" — neutral, feature-focused
- Urgency (Problem-Aware): "This export includes a watermark" — calls out the problem directly
- Benefit-Focused: "Export crisp PNGs at up to 8x resolution" — leads with the outcome
Navigation Layout Testing
I also tested where and how the Pro upgrade button appears in navigation — right side vs. left side, with vs. without the Learn/More dropdowns, and gradient button vs. standard styling. The hypothesis was that moving Pro into the left navigation (near the diagram type selector) would catch users earlier in their workflow.
Early Results
March numbers showed strong experiment exposure but modest conversion:
- Watermark impressions: 813
- Upgrade modal views: 60
- Post-export modal views: 280
- First paying subscriber: 1
One paying customer in month one is a validation signal, not a revenue story. The experiments are still gathering data, and the conversion path needs work — but the product-market signal is clear from the usage metrics.
Global Reach from Day One
The geographic distribution was surprisingly broad:
The US was the top country at 16% of traffic, followed by Brazil (11%), India (7%), Germany (6%), and France (6%). Over 25 countries had significant traffic. Edge browser accounted for 24% of sessions — unusually high and suggestive of enterprise/business users who are diagramming for work.
This distribution aligns with the GEO hypothesis: AI chatbots recommend tools globally without geographic bias. When ChatGPT tells a developer in São Paulo to "try mermaideditor.io", it has the same recommendation weight as for a developer in San Francisco.
Tech Decisions I'd Make Again
Monaco Editor over CodeMirror. Monaco's built-in TypeScript tooling, minimap, and multi-cursor support make it feel like VS Code in the browser. The monaco-mermaid package adds syntax highlighting and autocompletion for Mermaid syntax. The editor experience is one of the biggest differentiators.
Client-side rendering for diagrams. Mermaid.js runs entirely in the browser. No server-side rendering, no headless Chrome, no API calls. This keeps latency at zero for preview updates and eliminates server costs for the core editing experience.
PostHog over Mixpanel/Amplitude for analytics. Self-hostable, generous free tier, session replays, feature flags, and the A/B testing framework all in one platform. Being able to watch session recordings of users struggling with the export flow directly informed the UI improvements.
Stripe for payments with a lifetime deal option ($39 one-time). Lifetime deals are controversial in SaaS, but for a tool with near-zero marginal cost per user, they're a strong acquisition lever early on. One-time payments have lower friction than subscriptions for developer tools.
What's Next
The immediate roadmap is focused on the conversion funnel — the product has strong engagement (18,743 chart saves, 3-10 minute sessions) but the editor-to-paying-customer path needs optimization. The A/B tests are still in early innings.
On the product side: team workspaces, version history, and a REST API for programmatic diagram generation are the most-requested features. The AI repair feature has the most growth potential — it's already the most-used AI feature and directly solves a real pain point.
The GEO strategy will continue to be a focus. When 25% of your traffic comes from AI chatbots, optimizing for AI discoverability is just as important as traditional SEO.
MermaidEditor.io is free at mermaideditor.io. The source code is private but I'm happy to discuss the architecture — reach out on X or schedule a call.