---
title: "Mermaid Diagrams You Can Actually Draw On"
description: "Every Mermaid editor renders your flowchart and stops there. This one puts the diagram on a canvas so you can circle the bottleneck, add an arrow and export the annotated result — and the diagram stays editable afterwards."
canonical: "https://www.razi.pro/blog/mermaid-diagram-editor-with-annotation"
date: "2026-09-07"
tags: ["Mermaid", "Diagrams", "Documentation", "Tools", "How-To"]
source: "razi.pro"
---

# Mermaid Diagrams You Can Actually Draw On

You have generated an architecture diagram from twelve lines of Mermaid. It is correct. Now you need to circle the service that keeps falling over, put an arrow on the retry path, and paste the result into a pull request.

That last step is where every Mermaid editor stops. They render the diagram and hand you an SVG. Anything you want to *say about* the diagram happens somewhere else, in a screenshot tool, in a different app, badly.

## Mermaid in ninety seconds

Mermaid is a text format that renders to diagrams. Three types cover most of what people need.

A flowchart, where you declare nodes and the arrows between them:

    graph TD
      A[Request] --> B{Cached?}
      B -->|yes| C[Return cached]
      B -->|no| D[Fetch upstream]
      D --> E[Write cache]
      E --> C

A sequence diagram, for anything with a time axis:

    sequenceDiagram
      Client->>API: POST /order
      API->>Queue: enqueue job
      API-->>Client: 202 Accepted
      Queue->>Worker: deliver
      Worker->>DB: write result

And a state diagram, for lifecycles:

    stateDiagram-v2
      [*] --> Pending
      Pending --> Running
      Running --> Failed
      Running --> Done
      Failed --> Pending

Class and entity-relationship diagrams work too. The full syntax reference belongs to the Mermaid project and it is good; this is only enough to get a diagram on screen.

## Putting one on the canvas

Open the [drawing canvas](https://www.razi.pro/tools/draw), choose the diagram tool, and paste your Mermaid source. It renders and lands on the canvas.

What arrives is not a locked-off preview pane. It is an element on the same surface as the pencil — you can select it, drag it where you want it, and put things next to it.

Rendering happens in your browser. Mermaid is bundled into the page, so your diagram source is not sent anywhere to be turned into a picture.

## Annotating it

This is the part that does not exist anywhere else, so it is worth being concrete about what it buys you.

Switch to the pencil and draw on the diagram. Circle the node that is the bottleneck. Take the arrow tool and point at the edge that retries. Drop a text label next to it saying "this one times out at 30s". Use a filled rectangle to redact a hostname before the screenshot goes in a ticket.

None of that modifies the Mermaid source — the annotations are separate elements sitting above the rendered diagram. Which means you can move the diagram and your circle stays where it was, so put the diagram where you want it before you start marking it up.

> **The diagram stays editable, which is easy to miss.**
> The rendered diagram keeps its Mermaid source attached. Reopen it, change a line, and it re-renders **in place** — same position on the canvas, new picture. You are not deleting the old one and re-adding it, and your annotations survive. This is the difference between a diagram you can revise and a screenshot of a diagram, and it is the reason to build the flowchart here rather than paste in an image from elsewhere.

## Exporting

Download the PNG and you get the diagram and everything you drew on it, flattened into one image at the canvas's real resolution. That is the artefact you paste into a pull request or a Slack thread.

Save the project as JSON instead and you get the editable version — diagram source, annotations and positions preserved. Keep that alongside the code if the diagram documents something that will change.

## When the diagram will not render

Mermaid is strict, and the failure mode here is worth knowing because the visible message is not the useful one.

If the source does not parse, you get an alert saying the diagram could not be rendered and to check the syntax. That alert is deliberately generic. **The actual parse error — the line number and the token Mermaid choked on — is written to the browser console.** Open developer tools, look at the console, and you will see what it actually objected to. Without that, you are guessing.

The errors that produce it most often, in rough order:

**A missing diagram type on line one.** Mermaid needs to know what it is parsing before anything else. `graph TD`, `sequenceDiagram`, `stateDiagram-v2`. Start with node definitions and it fails immediately.

**Unescaped characters in a label.** Parentheses and brackets inside node text collide with the bracket syntax that defines node shape. Wrap the label in quotes: `A["handle(request)"]` rather than `A[handle(request)]`.

**Mixed diagram grammars.** Sequence arrows (`->>`) inside a `graph` block, or flowchart arrows inside a `sequenceDiagram`. Each type has its own arrow vocabulary and they are not interchangeable.

All three of those were checked against the bundled parser rather than recalled. Blank lines inside an indented block, incidentally, are fine — that one gets repeated a lot and it is not true.

## When to use mermaid.live instead

Plainly, because there is a real answer here.

If you are iterating on syntax — writing a diagram from scratch, fighting the grammar, wanting instant re-render on every keystroke — the official live editor is the better tool. It is built for exactly that loop and it does it well.

Come here when the diagram is already right and the job has changed from *authoring* to *explaining*: you need to mark it up, point at something, and produce one image that carries the annotation with it.

Two tools, two moments in the same task.

If your diagram is going into a Markdown file rather than an image, the [Markdown converter](https://www.razi.pro/tools/markdown-converter) handles that side. And the canvas has a longer feature list than diagrams alone — [the full-screen drawing canvas](https://www.razi.pro/blog/full-screen-drawing-canvas-online-free) covers the rest of it.