Merlay

Mermaid, your way.
A visual overlay editor for Mermaid diagrams in Obsidian.

Merlay lets you create and edit Mermaid diagrams visually directly inside your Obsidian notes. Build Flowcharts, State Diagrams, Sequence Diagrams, and Mindmaps with single-click relational sprouting, drag-and-drop connections, and inline renaming — without writing code or fighting diagram syntax.

Everything you create is saved as 100% standard, clean Mermaid syntax right inside your note. No proprietary lock-in, no layout drift, and fully compatible with Obsidian mobile, GitHub, and AI assistants.

Merlay is also available for VS Code and its forks (Devin, Cursor, VSCodium) on the VS Code Marketplace and Open VSX — same visual editor, same core.

---

📊 Supported Diagrams

Merlay provides interactive visual editing for 4 major Mermaid diagram types:

• Flowcharts (flowchart, graph)
• State Diagrams (stateDiagram-v2)
• Sequence Diagrams (sequenceDiagram)
• Mindmaps (mindmap)

All other diagram types open in a high-performance view mode with smooth pan and zoom.

---

✨ Features

• 🎯 Visual-First Editing: Click to select, sprout connected elements in one click, drag handles to connect, and double-click to edit text inline.
• 🎨 Universal Themes: Switch between Default, Dark, Neutral, Forest, and Base themes across all diagrams using standard Mermaid frontmatter.
• 🔄 Two-Way Sync: Changes reflect instantly in your note, with a slide-out drawer to view and tweak Mermaid source code live.
• ⚡ Native Obsidian Flow: Hover over any Mermaid block in Reading View or Live Preview and click Visual Mode, or insert templates via slash commands (/flowchart, /state, etc.).
• 📂 Standalone Files: Create and edit .mmd and .mermaid diagram files directly from the file explorer.
• 🔒 Zero Lock-In: Generates clean, human-readable Mermaid code with no custom comments or hidden layout data.

---

⚡ Quick Start

1. Open: Hover over any Mermaid block in your note and click Visual Mode (or type /flowchart, /state, /sequence, or /mindmap).
2. Edit: Sprout new items, drag connections, double-click to rename, or delete elements.
3. Save: Close the overlay — your note is updated automatically in real time.

---

⌨️ Controls

---

💡 Why Merlay? (Structural, Not Spatial)

Mermaid is a declarative, code-first diagramming language that computes its own layout. Traditional visual editors often attempt to impose arbitrary spatial coordinates onto diagrams, leading to broken round-trips, syntax corruption, and layout drift.

Merlay takes a structural approach:

• 1:1 Native Parity: Controls are overlaid directly on Obsidian's exact Mermaid SVG rendering — what you see is what you get.
• Topological Operations: You edit structure and relationships (elements and connections), while Mermaid computes clean, natural layouts automatically.
• Ultra-Lean Footprint: Zero heavy canvas framework dependencies. Bundled at just ~170 KB.

---

🚀 Installation

Obsidian

Install directly inside Obsidian:

1. Open Settings → Community plugins (ensure Restricted mode is turned off).
2. Click Browse and search for Merlay.
3. Click Install, then Enable.

(Or view on the Obsidian Community Directory).

VS Code & Forks (Cursor, Devin, VSCodium)

Install directly from:

• VS Code Marketplace
• Open VSX Registry

(Or search Merlay in your editor's Extensions view).

---

🛠️ Development

npm install     # Install dependencies
npm test        # Run tests
npm run build   # Build production bundles

Testing in the real apps

cp .env.example .env   # once: point MERLAY_VAULT_DIR at your vault
npm run install:obsidian   # build + install into your Obsidian vault (then Ctrl+R)
npm run install:vscode     # build + package + install into VS Code (then reload window)

For architecture details, see ARCHITECTURE.md.

---

Support

If Merlay saves you time, consider starring the repo — it helps others discover it.

---

📄 License

MIT License © 2026 Seyed Ali Hashemi