Skip to content
prdlkPublic
forked from inkeep/visimer

About

Visual editing for Mermaid diagrams.

Resources

Stars

0 stars

Watchers

0 watching

Forks

 
 

Repository files navigation

Visimer

Visual editor for Mermaid diagrams.

Visimer brings "what you see is what you get" editability to Mermaid diagrams. Rename labels, change shapes, add new nodes, etc. by live editing the rendered diagram.

MIT Renders with pele Types

A node label is double-clicked and retyped on the canvas; the matching line of Mermaid source rewrites live as it is typed


Why

AI is great for generating Mermaid diagrams that help explain concepts visually. We wanted to make it easy to edit fine details visually without digging into Mermaid syntax.

Usage

  • Use as a component library that can be embedded in any application.
  • Use with a Markdown editing app like OpenKnowledge to edit Mermaid diagrams in your markdown.

Read the launch post for the story and a live editable diagram.

Quick start

npm i @visimer/core @visimer/dom
import { MermaidWysiwygEditor } from '@visimer/core'
import { MermaidCanvasView } from '@visimer/dom'

const editor = new MermaidWysiwygEditor({
  code: 'flowchart TD\n  A[Start] --> B{OK?}\n  B -->|yes| C[Ship]',
})

new MermaidCanvasView({
  editor,
  container: document.querySelector('#canvas')!,
})

editor.on('change', ({ code }) => console.log(code)) // always-current source

Try everything locally:

pnpm install && pnpm dev   # playground at http://localhost:5173

Theming

Rendering is themed by CSS variables, set on the canvas container or any ancestor. Colors apply live with no re-render:

#canvas {
  --pele-bg: #0f1115;
  --pele-fg: #e6e6e6;
  --pele-accent: #6366f1;
}

Available variables: --pele-bg, --pele-fg, --pele-muted, --pele-line, --pele-surface, --pele-surface-alt, --pele-border, --pele-accent, --pele-critical, --pele-error, --pele-font, --pele-font-mono, --pele-title-weight, --pele-heading-weight, --pele-bold-weight, --pele-radius, and series colors --pele-series-1 … --pele-series-8. Defaults are a light palette. Colors set in the source (style, classDef, linkStyle) are kept.

Fonts are measured when the diagram renders: after changing --pele-font, call view.refresh(). Other pele options (fontSize, padding, maxWidth, links, icons, …) go in renderOptions / view.setRenderOptions(...). Mermaid's %%{init}%% themes and theme/securityLevel configs do not apply.

Try with Open Knowledge

OpenKnowledge is a markdown editor that allows WYSIWYG editing of markdown files. It leverages Visimer as the native visual editor for Mermaid diagrams. Available as a Mac, Linux, and Windows IDE-style app or npm package.

What you can do

  • Edit text in place: double-click any label and type right on the diagram; nodes grow as you type
  • Drag to connect nodes, states, classes, entities, participants, with a ghost edge preview
  • Drag to reorder sequence messages; the statements reorder in source
  • Popovers on every entity: shape/type/arrow pickers, cardinalities, color swatches, fragments, notes
  • One undo stack across canvas and code (⌘Z anywhere)
  • Error tolerant: broken syntax mid-keystroke never blanks the canvas
  • Lossless: unknown syntax is preserved verbatim; your diff is only what you changed

Diagram support

22 of 33 Mermaid diagram types are editable; the other 11 render view-only.

Type View Item editing Structural editing
flowchart ✅ ✅ ✅
sequence ✅ ✅ ✅
state ✅ ✅ ✅
class ✅ ✅ ✅
ER ✅ ✅ ✅
pie ✅ ✅ ✅
gantt ✅ ✅ ✅
journey ✅ ✅ ❌
timeline ✅ ✅ ❌
quadrant ✅ ✅ ❌
kanban ✅ ✅ ❌
mindmap ✅ ✅ ❌
treemap ✅ ✅ ❌
packet ✅ ✅ ❌
sankey ✅ ✅ ❌
radar ✅ ✅ ❌
gitgraph ✅ ✅ ❌
xychart ✅ ✅ ❌
requirement ✅ ✅ ❌
C4 ✅ ✅ ❌
architecture ✅ ✅ ❌
block ✅ ✅ ❌
swimlane ✅ ❌ ❌
agentflow ✅ ❌ ❌
railroad ✅ ❌ ❌
treeView ✅ ❌ ❌
cynefin ✅ ❌ ❌
wardley ✅ ❌ ❌
eventmodeling ✅ ❌ ❌
usecase ✅ ❌ ❌
venn ✅ ❌ ❌
ishikawa ✅ ❌ ❌
info ✅ ❌ ❌

Item editing is select, edit in place, add, and delete; structural editing adds connect, reorder, and restyle. Every type round-trips losslessly and syncs selection between code and canvas, including the view-only types. The last eleven rows are rendered by pele but have no semantic editing;

Packages

Package Purpose
@visimer/core Headless engine: lossless CST, semantic graphs, ops → minimal text edits, unified history. Zero DOM deps
@visimer/dom Interactive canvas: renders through pele, correlates SVG ⇄ graph, all gestures
@visimer/codemirror CodeMirror 6 pane: two-way sync, entity decorations, mermaid syntax highlighting, shared undo
@visimer/monaco Monaco binding for an editor instance you own; zero monaco dependency of its own
@visimer/react React bindings: <MermaidWysiwyg code onCodeChange /> drop-in component plus useMermaidEditor hook

The code-editor integration is a contract, not a dependency. core exposes bindTextPane, a five-method adapter that gives any editor the same two-way sync; the CodeMirror and Monaco packages are implementations of it, and neither is pulled in unless you install it (editor libraries are peer dependencies or absent entirely). Some other editor? Implement the adapter, it's about forty lines.

Architecture

  • Rendering is done by pele, a zero-dependency, synchronous Mermaid renderer themed by CSS variables. We overlay point-edit functionality on top.
  • We map the rendered SVG elements back (correlators key off pele's data-id attributes) to a Concrete Syntax Tree (CST) representation, which we can then use to edit only the parts of the Mermaid source that need updating (without affecting the rest of the file).

Design

flowchart TD
  SRC["Your Mermaid source"] --> MR["pele renderer (synchronous)"]
  MR --> SVG["Rendered SVG"]
  SVG --> COR["Correlator: SVG element → CST span"]
  COR --> OV["Point-edit overlay"]
  OV -->|"minimal text edit"| SRC
Loading

License

MIT © Inkeep

About

Visual editing for Mermaid diagrams.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages