Edit Mermaid diagrams visually with Visimer

Mermaid won, and still rules diagrams, by being text. It renders on GitHub, in IDEs, in any docs framework. Diffs are easy. Importantly, agents can work with it natively. We're not trying to fight any of that.

There's one moment everyone who works with Mermaid shares, though. You're looking at your rendered flowchart and you want to change one thing; a label, an arrow. Now you're scouring the source going: okay, which of these B -->|yes| C lines is the box I'm looking at?

You find it. Then you remember hexagons are {{ }}, or was it [( )]? You re-render to check. Renaming a participant in a sequence diagram is its own small project: the declaration, every arrow that mentions it, the Note over you forgot about.

None of this is hard. It's just a lot of typing for a change your eyes already made, and even more syntax to remember.

So we made the render editable

OpenKnowledge is our open-source knowledge base for you and your agents. As of this week, every Mermaid diagram in it is a live canvas.

Click a node and a little popover shows up on the diagram: shape, colors, arrow types, duplicate, delete. Double-click a label and just type. It's not full drag-and-drop, but it's powerful within the constraints of the Mermaid renderer.

Here's the part we care about most: underneath, all of that is still just editing your text. Rename a participant and every arrow pointing at it updates. Retype an edge and the diff is one line. Your comments and formatting stay exactly where you left them. Run git diff afterwards and it looks like a careful human did it.

Open a markdown file with a ```mermaid fence, or a plain .mmd file, and click things. Documents are collaborative, so one of you can type in the source pane while the other edits on the canvas; same text, two surfaces.

The tempting design we didn't build

Our first sketch had a model in the middle: parse the diagram into a tidy data structure, let the canvas edit that, then print a fresh file from it when you save. The problem is the printing. The data structure only keeps what it understands; comments, blank lines, and the order you wrote things in all get dropped on the way in, so the printer has to make them up on the way out. You rename one node; the diff says you rewrote the whole file. That's how an editor loses your trust.

So the canvas never owns anything. Parsing just records where every node and edge lives in the text, and each interaction becomes a tiny edit at exactly that spot; the same edit you'd have typed, minus the hunting. Bytes we don't understand are bytes we never touch, so comments and formatting survive untouched. And undo is just undoing text.

The other thing we refused to build was a renderer. Mermaid draws the SVG, exactly the way it draws it everywhere else, so the diagram you're editing is pixel-for-pixel the one your README or IDE will show. A small correlator we built matches each rendered element back to its source line, and the interaction hangs off that. When it can't match something, that piece is simply view-only: the diagram still renders, the text is still editable, nothing breaks. Half-typed syntax doesn't blank the canvas either; you keep the last good render while you finish the line.

One rename on the canvas, a one-line diff in the source. Recorded in the Visimer playground.

The editing engine turned out to be useful on its own, so it ships as a standalone MIT-licensed library: Visimer. A headless core (@visimer/core) with DOM, React, CodeMirror, and Monaco bindings as scoped packages. OpenKnowledge is just the first thing built on it.

Try it in the playground at visimer.com, or drop it into your own editor with npm i @visimer/react. The library lives at github.com/inkeep/visimer.