VsMerMark Editor for Visual Studio - User Guide

Summary

VsMerMark Editor is a Visual Studio 2022+ extension for editing and previewing Mermaid diagrams and Markdown documents with embedded Mermaid code blocks. It provides a complete authoring workflow with live preview, syntax highlighting, interactive diagram exploration, C#-to-diagram generation (including DevExpress XPO support), and multi-format export.

Developed by GiPStech. The extension was originally developed for internal use at GiPStech and is currently released as freeware. It extends the built-in Markdown and Mermaid editing capabilities of Visual Studio 2026, fully integrating into the IDE environment.

The extension was originally inspired by Mermaid Editor for Visual Studio by NeVeSpl (MIT License). VsMerMark Editor has been practically rewritten from scratch, retaining the core concept of a live Mermaid preview inside Visual Studio while adding extensive new capabilities: unified .mmd/.md handling, C# class diagram generation with Roslyn semantic analysis, XPO model support, interactive diagram highlighting, dark theme support, configurable styles, webpack-based build pipeline, and a comprehensive options page.

---

Table of Contents

1. License
2. Changelog
3. Features Overview
4. What VsMerMark Editor Adds
5. Installation
6. Getting Started
7. Editing Mermaid Diagrams
8. Editing Markdown with Embedded Diagrams
9. Generating Class Diagrams from C# Code
10. Generating XPO Diagrams
11. Smart Merge
12. Interactive Diagram Highlighting
13. Diagram Explorer
14. Exporting Diagrams
15. Syntax Highlighting
16. Dark Theme Support
17. Configuration and Options
18. Class Annotations with VsMerMarkNote
19. Supported Mermaid Diagram Types
20. Keyboard Shortcuts and Interactions
21. Troubleshooting
22. Attribution and Third-Party Licenses

---

License

Copyright (c) since 2025 GiPStech. All rights reserved.

VsMerMark Editor is distributed as freeware. You may use this extension free of charge for any purpose, including commercial and non-commercial use. Redistribution of the extension binary (VSIX package) is not permitted without prior written consent from GiPStech.

The extension periodically checks for newer versions. GiPStech may require users to update to the latest version within a reasonable time frame to continue using the extension.

THIS SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL GIPSTECH BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY ARISING FROM THE USE OF THIS SOFTWARE.

This extension includes third-party libraries distributed under the MIT License (see Attribution and Third-Party Licenses).

GiPStech reserves the right to change the licensing terms in future versions, including but not limited to introducing usage limits, feature restrictions, or paid tiers for some or all of the current functionality. Continued use of the extension is subject to the terms of the installed version.

---

Changelog

Version 1.0.0 (2025)

Initial release.

Editing and Preview

• Live preview of Mermaid diagrams with real-time rendering (debounced at 300ms)
• Unified .mmd / .md file support with auto-detection of pure Mermaid content
• Split preview panel (resizable) with toggle show/hide
• Detachable preview in a separate dockable window
• Mermaid theme selector (default, dark, neutral, forest)
• Automatic VS dark/light theme detection and synchronization

C# Class Diagram Generation

• Full class diagram generation from selected C# files using Roslyn Semantic Model
• Automatic partial class discovery across the entire project
• Stereotypes: <<abstract>>, <<interface>>, <<enumeration>>, <<struct>>, <<record>>, <<static>>
• Member visibility prefixes (+, -, #, ~) with static ($) and abstract (*) suffixes
• Color-coded class styles: abstract (red), concrete (green), placeholder (gray) with configurable colors and transparency

DevExpress XPO Diagram Generation

• Specialized XPO mode: public properties only, [Association]-based relationships
• [Aggregated] attribute detection for aggregation vs. association distinction
• Automatic placeholder generation for association targets not in selection

Smart Merge

• Incremental diagram updates preserving manual edits
• Merge rules: update C# classes, keep manual additions, regenerate relationships for selected classes
• Note and style preservation during merge operations

Interactive Features

• Click-to-highlight class nodes (bold border, darker colors)
• Click-to-highlight relationship lines (thicker orange stroke, 20px hit areas)
• Ctrl+Click for multi-element selection
• Edge label highlighting synchronized with relationship highlighting
• Diagram Explorer tool window (View > Other Windows) with tree view of diagrams and classes
• "Show in diagram" navigation: centers class in both the preview and the source editor
• Zoom support with Ctrl+mouse wheel in the preview panel

Export

• HTML export (standalone page with embedded SVGs and styles)
• PNG export (full-page WebView2 capture)
• SVG export (vector graphics, multi-diagram support with numbered files)

Syntax Highlighting

• Mermaid syntax: keywords, comments, strings, type names, arrows, stereotypes, properties, relationship labels
• Markdown syntax: headings, bold, italic, code, links, images, blockquotes, lists, tables, strikethrough

Configuration

• Tools > Options page with categorized settings (Preview, Diagram, Styles)
• Color picker with alpha/transparency slider for class styles
• Dropdown selectors for export format, theme, diagram direction
• Configurable diagram layout parameters (padding, node spacing, rank spacing)

Annotations

• [VsMerMarkNote("...")] attribute support for class-level notes in diagrams
• Attribute detected by name (no assembly reference required)

Context Menu Commands

• [VsMerMark] Generate Mermaid class diagram — Full mode
• [VsMerMark] Generate Mermaid XPO diagram — Properties-only mode
• [VsMerMark] Generate New ... — Creates new .mmd file when no diagram is active
• Open with VsMerMark Editor — Opens .md files with Mermaid preview

Build and Architecture

• Webpack-based JavaScript bundling (Mermaid 11.13.0, Marked 17.0.5)
• Single-file production bundle with all dependencies
• WebView2-based Chromium rendering engine
• VS 2022+ (17.0–18.0) targeting, x64 and ARM64

---

Features Overview

Feature	Description
Live Preview	Real-time rendering of Mermaid diagrams as you type, with debounced updates
Unified .mmd/.md Support	Seamless editing of pure Mermaid files and Markdown with embedded Mermaid blocks
C# Class Diagram Generation	Analyze C# source files with Roslyn and generate Mermaid classDiagram syntax
XPO Diagram Generation	Specialized mode for DevExpress XPO models (properties-only, association-based)
Smart Merge	Update existing diagrams without losing manual edits
Interactive Highlighting	Click/Ctrl+Click on classes and relationships to highlight them
Diagram Explorer	Tree view tool window listing all diagrams and classes with "Show in diagram" navigation
Multi-Format Export	Export to HTML, PNG, or SVG
Syntax Highlighting	Color-coded Mermaid and Markdown syntax in the editor
Visual Class Styles	Abstract (red), concrete (green), and placeholder (gray) classes with configurable colors
Dark Theme Support	Automatic adaptation to Visual Studio's light/dark theme
Configurable Options	Comprehensive Tools > Options page for styles, layout, and behavior
Class Annotations	Support for [VsMerMarkNote] attribute to add notes to diagram classes

---

What VsMerMark Editor Adds

Visual Studio 2026 includes a built-in Markdown editor with basic Mermaid rendering support. VsMerMark Editor extends these capabilities significantly:

Capability	VS 2026 Built-in	VsMerMark Editor
Mermaid preview	Basic rendering	Zoomable live preview with theme selection
Syntax highlighting	Generic code coloring	Advanced Mermaid-specific highlighting
Diagram interaction	None	Click and Ctrl+Click to highlight elements
Diagram navigation	Basic scrolling	Diagram Explorer tool window with class-level navigation
Diagram generation	None	Automatic generation from C# source code
DevExpress XPO support	None	Full association and aggregation support
Export formats	None	HTML, PNG, SVG
Dark theme	Partial	Full synchronization with VS theme
Configuration	None	Comprehensive options page

Automatic diagram generation

One of the key advantages of VsMerMark Editor is the ability to generate Mermaid class diagrams directly from C# source code. This eliminates the need to write Mermaid syntax manually, significantly increasing productivity and reducing errors. The generated diagrams stay synchronized with the code through the smart merge feature, which updates existing diagrams without losing manual edits.

---

Installation

1. Download the .vsix file or install from Visual Studio Marketplace
2. Double-click the .vsix to install, or use Extensions > Manage Extensions in Visual Studio
3. Restart Visual Studio after installation
4. The extension requires WebView2 Runtime (pre-installed with Windows 10/11 and modern VS versions)

Note: The extension targets Visual Studio 2022 (17.0) and later, both x64 and ARM64 architectures.

---

Getting Started

Opening a Mermaid file (.mmd)

Simply double-click any .mmd or .mermaid file in Solution Explorer. The editor opens automatically with the live preview panel on the right side.

Opening a Markdown file (.md) with preview

Right-click a .md file in Solution Explorer and select "Open with VsMerMark Editor". This opens the file in the text editor with the Mermaid-aware preview panel.

Tip: Double-clicking a .md file opens VS's built-in Markdown preview instead. Use the context menu command to get the VsMerMark preview with Mermaid support.

---

Editing Mermaid Diagrams

Pure Mermaid files (.mmd)

Create or open a .mmd file containing Mermaid syntax. The preview panel updates in real-time as you type.

Example content:

classDiagram
direction LR

class Animal {
    +name: string
    +age: int
    +makeSound()
}

class Dog {
    +breed: string
    +fetch()
}

Animal <|-- Dog : inherits

The preview renders the diagram immediately with configurable styles.

Markdown with embedded Mermaid blocks

Files can mix Markdown and Mermaid. Wrap Mermaid code in fenced code blocks:

# My Architecture Document

Some description here...

```mermaid
classDiagram
class UserService {
    +getUser(id)
    +createUser(data)
}
```

More markdown text below the diagram.

The preview renders both Markdown content and Mermaid diagrams in sequence.

---

Generating Class Diagrams from C# Code

Basic generation

1. Open or create a .mmd or .md file where you want the diagram
2. In Solution Explorer, select one or more .cs files (use Ctrl+Click for multi-selection)
3. Right-click and choose "[VsMerMark] Generate Mermaid class diagram"

The extension analyzes the selected C# files using Roslyn's Semantic Model and generates a complete class diagram including:

• Class hierarchy (inheritance and interface implementation)
• Properties with types and visibility
• Methods with parameters and return types
• Fields
• Stereotypes: <<abstract>>, <<interface>>, <<enumeration>>, <<struct>>, <<record>>, <<static>>

Generate New (no active diagram file)

If you select .cs files without having a .mmd or .md file open, the commands change to "[VsMerMark] Generate New Mermaid class diagram". This:

1. Generates the diagram content
2. Creates a new file named VsMerMark Diagram.mmd in the same directory as the first selected .cs file
3. Opens the file automatically with the preview panel

If a file with that name already exists, it appends a numeric suffix (VsMerMark Diagram_2.mmd, etc.).

Partial class support

The analyzer automatically discovers all partial class declarations across the entire project. You only need to select one part of a partial class; the extension finds all other parts (Designer.cs, Generated.cs, etc.) via Roslyn's DeclaringSyntaxReferences.

Visual class styles

Generated diagrams use color-coded styles to distinguish class types:

Class Type	Default Color	Description
Abstract	Light red (#f8d7daB3)	Abstract classes, interfaces
Concrete	Light green (#d4eddaB3)	Regular concrete classes
Placeholder	Light gray (#f0f0f080)	Base classes not in selection (external)

Colors are configurable in Tools > Options (see Configuration).

The semi-transparent fill (70% opacity by default) allows relationship lines passing beneath class boxes to remain visible.

Visibility prefixes in generated members

Prefix	Meaning
+	Public
-	Private
#	Protected
~	Internal

Suffixes: $ for static members, * for abstract members.

---

Generating XPO Diagrams

For projects using DevExpress XPO (eXpress Persistent Objects), the extension provides a specialized diagram mode:

1. Select .cs files containing XPO persistent classes
2. Right-click and choose "[VsMerMark] Generate Mermaid XPO diagram"

Differences from Full mode

Aspect	Full Mode	XPO Mode
Members shown	Properties, methods, fields	Public properties only
Associations	All type references	Only properties with [Association] attribute
Relationship types	All	Collection relationships (1:N) only
Aggregation	Not distinguished	[Aggregated] properties shown with diamond (o--)
External classes	Placeholders for base classes only	Placeholders for base classes AND association targets not in selection

---

Smart Merge

When you generate a diagram with the cursor inside an existing mermaid block, the extension performs a smart merge instead of replacing the entire block:

Merge rules

• Classes in C# and in block: Updated with new member definitions
• Classes in C# but not in block: Added to the diagram
• Classes in block but not in C#: Kept unchanged (preserves manual additions)
• Relationships for selected classes: Replaced with fresh analysis
• Relationships for non-selected classes: Kept unchanged
• Notes and styles: Regenerated for C# classes, preserved for manually-added classes

This allows you to incrementally build diagrams, adding classes from different parts of the codebase while preserving manual layout adjustments and custom annotations.

---

Interactive Diagram Highlighting

Click on diagram elements in the preview to highlight them:

Interactions

Action	Behavior
Click on a class	Highlights the class (bolder border, darker colors)
Click on a relationship line	Highlights the relationship (thicker line in orange) and its label
Ctrl+Click	Adds elements to the current selection (multi-select)
Click on empty space	Clears all highlighting

Relationship lines have an invisible 20px-wide hit area for easy clicking, even on thin lines.

---

Diagram Explorer

The VsMerMark Diagram Explorer is a dockable tool window that provides a structured tree view of all Mermaid diagrams and their classes in the active file. It is especially useful for navigating large diagrams with many classes.

Opening the Diagram Explorer

Go to View > Other Windows > VsMerMark Diagram Explorer.

The tool window appears docked in the IDE (by default, alongside Solution Explorer). It remains open across sessions and automatically updates when you switch between files.

Tree structure

The explorer displays a hierarchical view of the active file's content:

• For files with a single diagram: One root node ("Diagram") with class names as children
• For files with multiple diagrams (e.g., Markdown with several ```mermaid blocks): Multiple root nodes ("Diagram 1", "Diagram 2", ...) each with their own class children

Class names are extracted automatically from class ClassName declarations in the Mermaid source and listed alphabetically.

Show in diagram

Right-click on any class in the tree and select "Show in diagram" (or double-click the class). This performs two synchronized actions:

1. Diagram preview — The WebView2 panel scrolls to center the selected class and temporarily highlights it with a bold border for 2 seconds
2. Text editor — The source editor scrolls to center the class ClassName definition and positions the cursor there

This dual navigation makes it easy to jump between the visual representation and the source code of any class, even in diagrams with dozens of classes.

Automatic updates

The tree view updates automatically when:

• The content of the active file changes (debounced at 500ms to avoid excessive refreshes while typing)
• The user switches to a different file in the editor
• The active editor is closed (the tree clears with a "No diagram file open" message)

Supported file types

The explorer activates for .mmd, .mermaid, and .md files. For other file types, it displays "No diagram file open".

---

Exporting Diagrams

Use the "Save rendered diagram" button in the preview toolbar to export:

Format	Description
HTML	Standalone HTML page with embedded SVG diagrams and all styles (default)
PNG	Full-page screenshot via WebView2's CapturePreview
SVG	Vector graphics extracted from Mermaid's rendered output. Multiple diagrams produce numbered files (diagram_1.svg, diagram_2.svg, etc.)

The export format is selectable from the combo box in the toolbar.

Syntax Highlighting

The editor provides syntax highlighting for both Mermaid and Markdown content, using Visual Studio's theme colors for consistent appearance.

Mermaid highlighting

• Keywords: Diagram types (classDiagram, graph, sequenceDiagram, etc.) and Mermaid keywords (class, subgraph, end, direction, etc.)
• Comments: Lines starting with %%
• Strings: Quoted text
• Type names: Class names, type annotations
• Arrows/Punctuation: Relationship arrows (-->, <|--, o--, etc.) and visibility modifiers (+, -, #, ~)
• Property names: Field/property declarations
• Stereotypes: <<abstract>>, <<interface>>, etc.
• Fence markers: Opening ```mermaid and closing ``` markers (dimmed)

Markdown highlighting

Headings, bold, italic, inline code, links, images, blockquotes, lists, horizontal rules, strikethrough, tables, and code fences are all highlighted.

---

Dark Theme Support

The extension automatically detects Visual Studio's current theme and adapts:

• WPF controls (toolbar, buttons, combo boxes, splitter) use VS Shell themed brushes
• Preview HTML switches between light and dark CSS variables
• Mermaid diagrams automatically switch to the dark theme when VS is in dark mode (if the Mermaid theme is set to "default")

Theme changes are detected in real-time via VSColorTheme.ThemeChanged event.

---

Configuration and Options

Access extension settings via Tools > Options > VsMerMark Editor > General.

Preview settings

Option	Default	Description
Default Export Format	html	Format for diagram export (html, png, svg)
Default Theme	default	Mermaid rendering theme (default, dark, neutral, forest)
Default Preview Width	666 px	Width of the preview panel
Default Preview Height	600 px	Height for the detached preview window

Diagram settings

Option	Default	Description
Default Direction	LR	Diagram layout direction: LR (left-to-right) or TB (top-to-bottom)
Class Padding	20	Padding inside class boxes
Node Spacing	80	Horizontal spacing between diagram nodes
Rank Spacing	100	Vertical spacing between diagram ranks

Style settings

All colors use hex format with alpha channel (#RRGGBBAA). A custom color picker with alpha slider is provided for easy selection.

Option	Default	Description
Abstract Class Fill	#f8d7daB3	Fill color for abstract classes (light red, 70% opacity)
Abstract Class Stroke	#f5c6cbB3	Border color for abstract classes
Concrete Class Fill	#d4eddaB3	Fill color for concrete classes (light green, 70% opacity)
Concrete Class Stroke	#c3e6cbB3	Border color for concrete classes
Placeholder Class Fill	#f0f0f080	Fill color for external/placeholder classes (gray, 50% opacity)
Placeholder Class Stroke	#cccccc80	Border color for placeholder classes

Class Annotations with VsMerMarkNote

Add descriptive notes to classes in the generated diagram by using the [VsMerMarkNote] attribute in your C# code:

[VsMerMarkNote("Abstract base for all vehicle types with tracking and maintenance support")]
public abstract partial class Vehicle : VehicleBase
{
    // ...
}

This generates a Mermaid note in the diagram:

note for Vehicle "Abstract base for all vehicle types with tracking and maintenance support"

How to use

1. Define the attribute in your project (any namespace):

[AttributeUsage(AttributeTargets.Class | AttributeTargets.Interface | AttributeTargets.Enum | AttributeTargets.Struct)]
public class VsMerMarkNoteAttribute : Attribute
{
    public string Text { get; }
    public VsMerMarkNoteAttribute(string text) { Text = text; }
}

2. Apply it to any class, interface, enum, or struct
3. Generate the diagram as usual

The extension searches for the attribute by name (not by assembly reference), so you do not need to reference the extension's assembly. Just define the attribute anywhere in your solution.

---

Supported Mermaid Diagram Types

The extension supports all Mermaid diagram types for preview rendering. The auto-detection heuristic (for files without ```mermaid fences) recognizes:

Diagram Type	Keyword
Class Diagram	classDiagram
Flowchart	graph, flowchart
Sequence Diagram	sequenceDiagram
ER Diagram	erDiagram
State Diagram	stateDiagram, stateDiagram-v2
Gantt Chart	gantt
Pie Chart	pie
Git Graph	gitGraph
User Journey	journey
Mind Map	mindmap
Timeline	timeline
Sankey	sankey-beta
XY Chart	xychart-beta
Block Diagram	block-beta
Quadrant Chart	quadrantChart
Requirement Diagram	requirementDiagram
C4 Diagrams	C4Context, C4Container, C4Component, C4Dynamic, C4Deployment
Kanban	kanban

Note: C# class diagram generation is specific to classDiagram. All other diagram types are supported for editing and preview only.

---

Keyboard Shortcuts and Interactions

Action	How
Generate class diagram	Right-click .cs files > [VsMerMark] Generate Mermaid class diagram
Generate XPO diagram	Right-click .cs files > [VsMerMark] Generate Mermaid XPO diagram
Open .md with preview	Right-click .md file > Open with VsMerMark Editor
Toggle preview panel	Click "Split preview" in the top toolbar
Detach preview	Click "Open preview" in the top toolbar
Highlight class	Click on a class in the preview
Multi-select highlight	Ctrl+Click on classes/relationships
Clear highlighting	Click on empty space in the preview
Resize preview	Drag the splitter between editor and preview
Open Diagram Explorer	View > Other Windows > VsMerMark Diagram Explorer
Navigate to class	Right-click class in Diagram Explorer > Show in diagram (or double-click)
Zoom in/out diagram	Ctrl + mouse wheel in the preview panel

---

Troubleshooting

Preview shows "WebView2 Runtime" message

Install the Microsoft Edge WebView2 Runtime. It is required for the preview panel.

No diagram rendered

• Ensure the Mermaid syntax is valid. Check the error panel below the preview for parsing errors.
• Make sure the file has a recognized extension (.mmd, .mermaid, or .md).

C# generation shows "No classes found"

• The solution must compile successfully. The Roslyn Semantic Model requires a compilable solution.
• Ensure you have selected .cs files (not folders or other file types).

Settings show "legacy options" warning in VS 2026

• This is expected behavior. Visual Studio 2026 displays DialogPage-based extension settings through a legacy compatibility layer. The settings work correctly.

Diagram looks different after generating

• Check your Options (Tools > Options > VsMerMark Editor) for direction, spacing, and style settings.
• The diagram layout depends on the Mermaid engine's auto-layout algorithm, which may vary with different content.

---

Attribution and Third-Party Licenses

All product names, trademarks, and registered trademarks mentioned in this document — including DevExpress, XPO, Visual Studio, Mermaid, and others — are property of their respective owners. Their use here is for identification purposes only and does not imply endorsement or affiliation.

VsMerMark Editor was inspired by and originally based on Mermaid Editor for Visual Studio by NeVeSpl, licensed under the MIT License. The original extension provided a lightweight editor for Mermaid files with live preview and SVG/PNG export.

VsMerMark Editor has been practically rewritten from scratch, retaining only the foundational concept of a WebView2-based Mermaid preview inside Visual Studio. Major new capabilities include:

• Complete C#-to-Mermaid generation pipeline using Roslyn semantic analysis
• DevExpress XPO model support with specialized association/aggregation handling
• Smart merge algorithm preserving manual diagram edits
• Interactive diagram highlighting with click/Ctrl+Click
• Unified .mmd/.md handling with auto-detection of pure Mermaid content
• Configurable class styles with color picker and alpha transparency
• Dark theme support with automatic VS theme detection
• Options page with diagram layout parameters
• Class annotations via [VsMerMarkNote] attribute
• Webpack-based build pipeline replacing vendored JS libraries
• Comprehensive syntax highlighting for both Mermaid and Markdown

Third-party libraries

Library	Version	License	Purpose
Mermaid.js	11.13.0	MIT	Diagram rendering engine
Marked.js	17.0.5	MIT	Markdown parsing
Microsoft.CodeAnalysis (Roslyn)	4.3.0	MIT	C# semantic analysis
WebView2	1.0.3595.46	Microsoft	Chromium-based web rendering

Syntax highlighting

Mermaid and Markdown syntax highlighting is implemented natively using Visual Studio's MEF classification framework (IClassifier), with no external TextMate grammars. The classifier maps to VS built-in classification types so that colors automatically follow the user's current theme.