Markdown Editor: Split View vs Single Pane Mermaid Docs

It's 2:47 AM and Your Architecture Diagram Just Broke the Entire Doc

You're staring at a 47-page technical document. Twelve embedded screenshots of system architecture. Three flowcharts exported as PNGs from a desktop tool you closed two hours ago. The API changed at 11 PM. Now every diagram is wrong, every screenshot is stale, and the Word file keeps crashing when you try to re-import the updated images.

I've been there. Last quarter, I spent 6.5 hours just re-exporting and re-embedding diagrams after a single API revision. Six and a half hours. For one update cycle.

Here's the thing: that time is completely recoverable. The problem isn't your diligence. It's the toolchain.

The Problem: Diagrams and Text Live in Separate Worlds

Traditional documentation workflows treat diagrams as foreign objects. You write text in one application. You build diagrams in another. You export. You embed. You pray nothing shifts.

When a reviewer asks for a small change—say, adding an authentication step to a sequence diagram—you reopen the diagram tool, make the edit, re-export, re-import, resize, and re-align. That's 4 to 7 minutes per diagram per revision. With 12 diagrams and an average of 3 revision rounds, you're looking at roughly 252 minutes—over 4 hours—just on diagram maintenance. For a single document.

The root cause is structural. Text and visuals are stored in different formats, managed by different tools, and coupled only by fragile file references. Every change creates cascading manual work.

Why Static Diagrams Fail Revision Cycles

Static images can't be diffed. Your version control system sees a binary blob. When you push an updated PNG, Git can't tell you what changed inside it. Reviewers can't leave inline comments on a specific arrow or node. And you certainly can't search for "OAuth" inside a flattened image file.

This is where text-based diagramming changes the math entirely.

The Solution: Mermaid + Web-Based Markdown Editor with Split View

Mermaid is a JavaScript-based diagramming language that lets you generate flowcharts, sequence diagrams, class diagrams, Gantt charts, and more using plain text syntax. When you pair it with a web-based markdown editor that offers a live split view, your diagrams and prose live in the same file, update in real time, and version cleanly in Git.

Let me walk you through the exact workflow I use for every technical document I ship. No fluff. Just steps.

Step 1: Choose the Right Web-Based Markdown Editor

Not every markdown editor supports Mermaid rendering. Before you start, verify these three things:

- The editor renders Mermaid blocks live in the preview pane (not just in exported HTML) - The split view is true side-by-side, not a toggle that hides your source - Changes in the editor pane reflect in the preview within 1 second

If your editor passes all three checks, you're set. If it doesn't, switch. There's no workaround for an editor that can't render Mermaid—it's a foundational requirement.

Step 2: Set Up Your Document Skeleton

Open a new file in your web-based markdown editor. Enable split view so your source is on the left and the rendered preview is on the right. Create this skeleton:

# Service Authentication Architecture

## Overview
Brief description of the auth flow.

## Architecture Diagram

```mermaid
flowchart TD
    A[Client Request] --> B[API Gateway]
    B --> C{Token Valid?}
    C -->|Yes| D[Route to Service]
    C -->|No| E[Return 401]
```

## Sequence Flow

```mermaid
sequenceDiagram
    participant C as Client
    participant G as Gateway
    participant A as Auth Service
    C->>G: Request with token
    G->>A: Validate token
    A-->>G: Valid
    G-->>C: 200 OK
```

As you type each Mermaid block, the right pane renders it immediately. You see the diagram take shape character by character. No export step. No context switch.

Step 3: Write Prose Around the Diagrams

Here's where the split view earns its keep. While your left pane holds the raw markdown and Mermaid syntax, your right pane shows the polished output—headings, paragraphs, and fully rendered diagrams side by side.

Write your explanatory text directly beneath each diagram block. For the sequence diagram above, you might write:

"The gateway forwards the token to the auth service for validation. If the token is valid, the gateway routes the request to the target service. Invalid tokens result in an immediate 401 response with no further processing."

Because both text and diagram live in the same markdown file, a reviewer reading the rendered output sees them together. And when they ask you to add a refresh-token flow, you edit one block of text syntax—not a separate diagram file.

Step 4: Iterate Using Live Preview

This is the step where you recover those lost hours. When the API changes, you don't reopen a diagram tool. You scroll to the relevant Mermaid block in your editor, modify the syntax, and watch the right pane update instantly.

Let's say the auth team adds a rate-limiting check. You update the sequence diagram:

sequenceDiagram
    participant C as Client
    participant G as Gateway
    participant A as Auth Service
    participant R as Rate Limiter
    C->>G: Request with token
    G->>R: Check rate limit
    R-->>G: Within limit
    G->>A: Validate token
    A-->>G: Valid
    G-->>C: 200 OK

That edit took 40 seconds. In the old workflow—exporting from a diagram tool, re-importing, re-aligning—the same change would take 4 to 7 minutes. Across a document with 12 diagrams, that's a savings of roughly 50 minutes per revision round. Three revision rounds? You've just saved 2.5 hours on a single document.

Step 5: Version Control Everything

Because your entire document—prose and diagrams alike—is a single markdown file, Git tracks every change as readable text. A diff shows exactly which line of Mermaid syntax changed. Reviewers can comment on specific lines. You can revert a single diagram change without touching the rest of the document.

Store your markdown files in a Git repository. Use a standard naming convention like `docs/auth-architecture.md`. When someone asks "what changed in the last sprint," you run `git log --oneline docs/` and get an instant answer.

Step 6: Export and Share

When the document is final, your web-based markdown editor should offer export options. Most support HTML, PDF, or direct publishing. Because Mermaid renders client-side, the exported HTML will display diagrams correctly in any modern browser.

For PDF export, verify that your editor's export engine supports Mermaid. Some editors strip Mermaid blocks during PDF conversion. Test with a small document first—export a single diagram to PDF and confirm it appears. If it doesn't, check whether your editor offers a "Mermaid-enabled export" toggle or a server-side rendering option.

A Checklist for Every Mermaid Document

Before I mark any technical document as complete, I run through this checklist:

- Every diagram has a preceding heading and explanatory paragraph - Mermaid syntax is valid (no red error indicators in the preview pane) - Diagram labels use consistent terminology with the surrounding prose - All sequence diagram participants are introduced in prose before the diagram appears - The document exports correctly to the target format with diagrams intact - The file is committed to Git with a descriptive commit message

This checklist takes about 5 minutes to run through. It catches 90% of the issues that would otherwise surface during review.

The Workflow That Stays With You

Once you internalize this workflow, the old cycle of diagram-tool-then-word-processor feels archaic. You stop thinking of diagrams as separate artifacts. They become paragraphs that happen to render as visuals. Your editing speed increases. Your revision cycles shorten. Your documents stay coherent because text and diagrams evolve together in the same file, in the same editor, in the same window.

The next time an API changes at 11 PM, you won't be re-exporting screenshots at 2 AM. You'll open your web-based markdown editor, enable split view, edit three lines of Mermaid syntax, watch the diagram update live, and commit. Thirty seconds. Then you go to sleep.