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.

New companion extension — VsMerMark AzDevOps. A companion product, VsMerMark AzDevOps, is now available on the Visual Studio Marketplace. It brings the same Markdown and Mermaid rendering engine to Azure DevOps work items through a dedicated VsMerMark Attachments Preview tab that displays .md, .mmd, and .mermaid attachments inline — with full support for all Mermaid 11 diagram types, interactive click-highlighting, and automatic dark-mode. Because both extensions share the same rendering engine, diagrams generated by VsMerMark Editor render pixel-identically when attached to Azure DevOps work items, keeping documentation authoring and work tracking perfectly in sync.

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.2.0 (June 2026)

New Features

• Per-diagram zoom & pan in the Markdown preview. Each Mermaid diagram is rendered inside a fixed-height box (page width) with its own zoom (mouse wheel / toolbar) and pan (drag), so zooming a diagram no longer scales the surrounding Markdown text. Each box has a small toolbar (zoom in / out / fit-width).
• "Add to diagram" from Solution Explorer. New context-menu actions "Add to class diagram…" and "Add to XPO diagram…" (visible when one or more .cs files are selected and a diagram document is open) analyze the selected classes and merge them into a chosen open diagram — with a file picker when several diagrams are open, and a diagram picker for files with multiple class diagrams (or to create a new one).

Bug Fixes

• Class inheritance is now rendered with a solid UML line instead of a dashed line (interface implementation keeps the dashed line).
• Fixed the Marketplace rating prompt never appearing for some users: the "shown" state was recorded even when the notification failed to display; it is now recorded only when the notification is actually shown, with a short retry if the notification host is not ready yet.

Version 1.1.1 (April 2026)

Minor changes and fixes.

Note: The Mermaid files generated by this extension (.mmd and .md with embedded Mermaid blocks) are now natively supported by the new companion extension VsMerMark AzDevOps, which renders them inline as attachments on Azure DevOps work items using the same rendering engine — ensuring pixel-identical visual output between Visual Studio and Azure DevOps.

Version 1.1.0 (April 2026)

Diagram Explorer

• Added Support for multiple diagram types: classDiagram, flowchart/graph, erDiagram, sequenceDiagram
• Added Click on a diagram root node scrolls the preview to that diagram

Improvements

• In XPO mode, external classes with [Association] properties now include the properties within the class placeholder
• In XPO Mode, a Not Aggregated relationship is now generated with a solid line (not dashed)

Bug Fixes

• Fixed XPO diagram merge: regenerating selected classes no longer adds methods/fields that are not relevant in XPO mode
• Fixed XPO diagram generation: 1:1 [Association] properties now generate relationships (previously only 1:N collections were included)
• Fixed "Show in diagram" command: centers the selected element in both the preview panel and the source editor
• Fixed XPO diagram generation: classes with [Aggregated] properties do not generate relationships end symbols (diamond)

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

What VsMerMark Editor Adds

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

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:

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

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

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

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:

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

Diagram settings

Style settings

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

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:

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

Keyboard Shortcuts and Interactions

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

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.