Markdown Editor v2 for Visual Studio

Download this extension from the Visual Studio Marketplace or get the CI build.

---

This extension delivers a full featured Markdown editor with live preview, syntax-aware editing, and turnkey workflows for GitHub flavored Markdown.

💡 Recommended pairing: Use Markdown Editor v2 for syntax-aware editing, live preview, navigation, and Markdown workflows. Pair it with Markdown Lint for validation, diagnostics, and automatic fixes. The two extensions are designed to work together.

Getting Started

1. Install the extension from the Visual Studio Marketplace or grab the latest CI build.
2. Open any .md file in Visual Studio to enable the Markdown editor.
3. Press F7 to cycle through Source, Split, and Preview views. Press Shift+F7 to cycle in reverse.
4. Visit Tools -> Options -> Text Editor -> Markdown to tune fonts, preview behavior, and custom assets.

Feature Highlights

Editing essentials

• Powered by Markdig, providing the best available Markdown parser.
• Syntax highlighting powered by Prism.js keeps fenced code blocks readable.
• Supports CommonMark, GitHub flavored Markdown, FrontMatter YAML, Mermaid, and math notation.
• Brace completion with type-through maintains list formatting and block structure.
• Lightning fast performance even in large documentation sets.

Live preview

• Live preview window with scroll sync and dark theme support.
• Source, Split, and read-only Preview views for editing or focused reading.
• Switch between vertical and horizontal layouts depending on the workspace.
• Automatically updates on each keystroke and tracks the editor caret.
• Honors custom CSS and HTML templates so the preview matches your documentation brand.

Navigation and structure

• Jump between headings from the NavigationBar, Document Outline, or generated table of contents.
• Document Outline tool window shows a persistent hierarchical view of all headings.
• Collapse or expand fenced code and HTML blocks to stay focused.
• Press F12 on a local link or image reference to open its source file and follow Markdown heading or line fragments.
• Follow VS Code-style line links ([link](./file.cs#L10)) to open a file and jump to a specific line and column.

Media workflows

• Drag and drop images directly from Solution Explorer or File Explorer.
• Paste images from the clipboard, name them relative to the document, and get friendly alt text automatically.

Productivity tools

• Extensive keyboard shortcuts speed up formatting, linking, commenting, and checklist maintenance.
• VS command URL links trigger Visual Studio commands straight from the preview pane.
• Generate .html output from markdown files and keep it nested under the source file in Solution Explorer.

The sections below dive deeper into each area and include screenshots for quick orientation.

Live Preview Window

Markdown documents can be viewed in three modes:

• Source - Show only the Markdown editor.
• Split - Show the Markdown editor and synchronized preview together.
• Preview - Show only the rendered document for focused, read-only viewing.

Use the document toolbar to select a mode directly. F7 cycles from Source to Split to Preview, while Shift+F7 cycles in reverse. Documents initially open in Source or Split mode according to the Open documents with preview setting.

Every time the markdown document is modified, the preview window will update.

The preview window is automatically scrolled to match the scroll position of the document. As the document is scrolled up and down, the preview window will follow.

Live preview can be managed in the settings.

The preview follows the document host's available size, including on high-DPI displays. Switching to Preview view and resizing the window preserves the saved split size for when you return to Split view.

The document toolbar fills the available width and adapts to the native Visual Studio toolbar height rather than clipping it to a fixed height.

When preview click synchronization is enabled, a plain click updates the source position without taking keyboard focus away from the preview. Selecting text or double-clicking a word does not trigger an additional source navigation.

Syntax highlighting

All fonts can be changed in Tools -> Options -> Environment -> Fonts and Colors dialog.

GitHub and other flavors

Advanced markdown extensions are supported to give more features to the syntax. This includes pipe tables, emoji, mathematics and a lot more.

Azure DevOps wiki syntax

The editor supports Azure DevOps wiki-specific syntax for generating a table of contents.

Table of Contents ([[_TOC_]]):

Add [[_TOC_]] anywhere in your document to automatically generate a table of contents based on all headings. The TOC renders as a nested list with links to each section.

[[_TOC_]]

# Introduction
## Getting Started
## Installation
# Advanced Topics

This syntax is case-sensitive and must appear on its own line, matching Azure DevOps wiki behavior.

Mermaid diagram support

The editor supports all Mermaid diagram types for visualizing complex information. Mermaid diagrams are rendered in the live preview window using the native Mermaid.js library.

Supported diagram types include:

• Flowcharts (flowchart or graph TB/LR) - For architectural diagrams, system designs, and process flows
• Sequence Diagrams (sequenceDiagram) - For operational flows like authentication, authorization, and API interactions
• Class Diagrams - For object-oriented designs
• State Diagrams - For state machine representations
• Entity Relationship Diagrams - For database schemas
• Gantt Charts - For project timelines
• Pie Charts - For data visualization
• And many more supported by Mermaid.js

Example - Flowchart:

```mermaid
graph TB
    A[Start] --> B{Decision}
    B -->|Yes| C[Action 1]
    B -->|No| D[Action 2]
    C --> E[End]
    D --> E
```

Example - Sequence Diagram:

```mermaid
sequenceDiagram
    participant User
    participant Frontend
    participant Backend
    participant Database
    
    User->>Frontend: Login Request
    Frontend->>Backend: Authenticate
    Backend->>Database: Query User
    Database-->>Backend: User Data
    Backend-->>Frontend: Auth Token
    Frontend-->>User: Login Success
```

Mermaid diagrams automatically adapt to the current Visual Studio theme (light or dark mode).

Standalone Mermaid files

In addition to Mermaid code blocks in Markdown, the extension also supports standalone Mermaid files with .mermaid or .mmd extensions. These files get:

• Custom file icons in Solution Explorer
• Syntax highlighting including Mermaid comments (%%)
• Live preview rendering the diagram

This is useful when you want to maintain complex diagrams as separate files or share them across multiple documents.

Root path configuration for Jekyll/GitHub Pages

When working with static site generators like Jekyll or GitHub Pages, you may want to use root-relative paths (paths starting with /) in your markdown files. The extension supports configuring a root path to properly resolve these paths in the preview.

Option 1: YAML front matter (per-file)

Add root_path to the YAML front matter of individual markdown files:

---
root_path: C:\Projects\myblog
title: My Blog Post
---

![Header Image](/images/header.jpg)
[About Page](/about.md)

Option 2: .editorconfig (project-wide)

Add md_root_path to your .editorconfig file to apply the setting to all markdown files in your project:

[*.md]
md_root_path = C:\Projects\myblog

This is useful when you want to set the root path once for an entire project rather than adding front matter to each file.

💡 Tip: Install the EditorConfig Language Service extension to get IntelliSense for the md_root_path property in your .editorconfig files.

Priority: YAML front matter takes precedence over .editorconfig, allowing per-file overrides when needed.

In these examples:

• The image path /images/header.jpg resolves to C:\Projects\myblog\images\header.jpg
• The link /about.md resolves to C:\Projects\myblog\about.md

Key features:

• Works with both images (src) and links (href)
• Supports Windows paths (C:\Projects\blog) and Unix paths (/home/user/website)
• Case-insensitive (root_path or ROOT_PATH in front matter)
• Can be quoted if the path contains spaces: root_path: "C:\My Projects\Site"
• Regular relative paths (not starting with /) can use .. while remaining within the preview root
• Paths starting with <http://,> <https://,> data:, or # are left unchanged

Preview path boundaries

For security, local images and links are rendered only when their resolved paths remain within the preview root. The preview root is selected in this order:

1. The root_path front matter or md_root_path EditorConfig setting.
2. The loaded solution directory or Open Folder root.
3. The nearest ancestor containing .git, a solution file, or a project file.
4. For a standalone file under Miscellaneous Files, the parent of the Markdown file's directory.

Relative references can traverse any number of parent directories as long as they remain inside that root. For example, ../../../shared/image.png works when shared is still within the loaded solution or Open Folder root. A standalone Miscellaneous File supports one parent level by default; configure root_path or md_root_path to allow references from a higher common root. References that escape the preview root are left unresolved.

Typical Jekyll structure:

myblog/
├── .editorconfig               ← Add md_root_path here
├── _posts/
│   └── 2024-01-15-my-post.md   ← Edit this file
├── images/
│   └── header.jpg              ← Referenced as /images/header.jpg
└── _config.yml

This feature is particularly useful when editing Jekyll blog posts where the actual URL structure differs from the file system layout.

Table formatting

Use Visual Studio's standard format commands to align and beautify pipe tables:

Ctrl+K, Ctrl+D formats all tables in the document.

Ctrl+K, Ctrl+F formats tables within the current selection.

Suggested action: When your cursor is inside a pipe table, a lightbulb suggestion offers Format Table to align and pad the table in place.

The formatter aligns columns, pads cells to consistent widths, and respects column alignment markers (:---, :---:, ---:).

Enable or disable this behavior in Tools -> Options -> Text Editor -> Markdown -> Advanced -> Auto-format tables.

Before:

| Name | Description | Price |
|---|:---:|---:|
| Widget | A small gadget | $9.99 |
| Gizmo | A larger device | $24.95 |

After:

| Name   | Description      |  Price |
|--------|:----------------:|-------:|
| Widget | A small gadget   |  $9.99 |
| Gizmo  | A larger device  | $24.95 |

Table sorting

Double-click any table header to sort the table by that column. Double-click again to toggle between ascending and descending order. Table headers are underlined to indicate they are clickable.

Before (unsorted):

| Name   | Price  |
|--------|-------:|
| Banana |  $1.25 |
| Apple  |  $0.99 |
| Cherry |  $2.50 |

After clicking "Name" header (sorted ascending):

| Name   | Price  |
|--------|-------:|
| Apple  |  $0.99 |
| Banana |  $1.25 |
| Cherry |  $2.50 |

The sorter handles numeric values intelligently, so columns with numbers sort numerically rather than alphabetically. Column alignment is preserved after sorting.

Enable or disable this feature in Tools -> Options -> Text Editor -> Markdown -> Advanced -> Enable table sorting.

IntelliSense

Emoji IntelliSense

You get full IntelliSense for over 1,600 emoji and smiley characters.

File path IntelliSense

When typing links [text]( or images ![alt](, IntelliSense provides completions for files and folders relative to the current document. This makes it easy to link to other markdown files or insert images without remembering exact paths.

• Folders are shown with a folder icon and automatically append / for continued navigation
• Typing / after selecting a folder retriggers completion to show contents of that folder
• Image files are prioritized when completing image links ![]()
• Markdown files are prioritized when completing regular links []()
• Supports relative paths including ./ and ../ navigation

Filesystem discovery runs in the background, and canceled or superseded completion requests are discarded so slow folders do not block typing.

Anchor IntelliSense

Type # inside a link to get completions for all headings in the current document:

[Jump to section](#heading-name)

Headings are shown with their level indicator (H1, H2, etc.) and automatically generate GitHub-compatible anchor slugs. Duplicate headings are handled with -1, -2 suffixes.

Headings ending in inline HTML icons no longer acquire an incidental trailing hyphen (for example, Flyout (<u>&#xF035C;</u>) links to #flyout). Explicit {#custom-id} anchors and literal hyphens are preserved. Links using the previous incidental trailing-hyphen IDs should be updated; legacy aliases are not generated.

Cross-document anchors: You can also get anchor completions for other markdown files by typing the file path followed by #:

[See other file](other-file.md#section-name)
[Relative path](../docs/guide.md#getting-started)

IntelliSense will parse the target markdown file and show all available headings.

Go to linked files

Place the caret anywhere on a local Markdown link or image reference and press F12 to open the referenced file. Inline and reference-style links are supported, along with relative paths, root-relative paths, local file URLs, generated .html links that map back to Markdown source files, and Jekyll collection paths.

Markdown heading fragments navigate directly to the matching heading. VS Code-style line fragments such as #L10, #L10,5, and #L10:5 navigate to the requested line and optional column. Remote URLs are left to Visual Studio's normal command handling.

Heading-based navigation

The NavigationBar shows all of the document headings, like a table of contents. Select a heading to jump to that section of the document.

Document Outline

The Document Outline tool window (View -> Document Outline) provides a persistent, hierarchical view of all markdown headings in your document. This is especially useful for navigating large documents.

Features:

• Hierarchical display - Headings are organized in a tree structure based on their level (H1-H6)
• Live synchronization - The outline updates automatically as you edit the document
• Click to navigate - Double-click any heading to jump to that location in the editor
• Caret tracking - The current heading is highlighted as you move through the document
• Theme support - Colors adapt to your Visual Studio theme (Light, Dark, Blue)

The Document Outline complements the NavigationBar dropdown by providing an always-visible overview of your document structure.

Line links to source files

Links to local files in the preview can include a VS Code-style line fragment to jump straight to a specific location when the file is opened. This is especially useful when an AI assistant generates links into your codebase.

Syntax:

• [link](./path/to/file.cs#L10) — opens file.cs and places the caret on line 10.
• [link](./path/to/file.cs#L10,5) — opens file.cs and places the caret on line 10, column 5. #L10:5 is also accepted.

Line and column numbers are 1-based and are clamped to the file's contents, so out-of-range values still open the file at the closest valid position. The targeted line is centered in the editor and focus is moved to the opened document.

Drag 'n drop images

Drag an image directly from Solution Explorer onto the document to insert the appropriate markdown that will render the image.

Paste images

This is really helpful for copying images from a browser or for inserting screen shots. Simply copy an image into the clipboard and paste it directly into the document. This will prompt you for a file name relative to the document and then it inserts the appropriate markdown.

It will even parse the file name and make a friendly name to use for the alt text.

Image Optimizer integration

This extension integrates with the Image Optimizer extension to optimize images.

Automatic optimization on paste: When you paste an image into a markdown document, it can be automatically optimized using lossless compression. This feature is enabled by default and can be toggled in Tools -> Options -> Text Editor -> Markdown -> Advanced -> Optimize images on paste.

Suggested actions: When your cursor is on an image reference in markdown (e.g., ![alt](image.png)), lightbulb suggestions appear offering:

• Optimize Image (Lossless) - Best quality, smaller file size
• Optimize Image (Lossy) - Best compression, minimal quality loss

Note: These features require the Image Optimizer extension to be installed. If it's not installed, you'll be prompted to download it.

Outlining

Any fenced code and HTML blocks can be collapsed, so that this:

...can be collapsed into this:

Keyboard shortcuts

Ctrl+Alt+R Refresh the preview window.

Ctrl+Alt+K Inserts a new link.

Ctrl+B makes the selected text bold by wrapping it with **.

Ctrl+I makes the selected text italic by wrapping it with _.

Ctrl+Space checks and unchecks task list items.

- [x] task list item

Tab increases indentation of list items.

Shift+Tab decreases indentation of list items.

Ctrl+K,C wraps the selection with HTML comments.

Ctrl+K,U removes HTML comments surrounding the selection/caret.

Markdown document toolbar

Markdown documents include a native Visual Studio toolbar above the editor. Use Source, Split, and Preview to switch directly between document views. F7 cycles forward through the views and Shift+F7 cycles backward.

The toolbar is initialized after the document tab becomes visible and its initial layout and rendering have run. Opening a Markdown file in a background tab does not initialize its native controls until that tab is selected. Once created, the toolbar is retained across tab switches and released when the document closes, rather than being torn down and recreated on each activation.

Preview browser controls are also created only for a visible preview, after initial layout and rendering. Source-only and background documents do not construct WebView2 controls on the initial file-opening path.

Caret, selection, and typing updates are coalesced over 150 ms. Formatting buttons share analysis of the current snapshot and selection instead of rescanning the document separately for each button.

Tables of contents enclosed in <!-- TOC --> markers are refreshed on save. Only changed contents are applied, in one buffer edit; an unchanged table of contents does not cause an additional save. Background TOC results are discarded if the document has been edited in the meantime.

Available actions:

• Paragraph/Heading dropdown - Convert selected lines to paragraph or heading levels 1-6
• Bold - Wrap selection with **
• Italic - Wrap selection with _
• Strikethrough - Wrap selection with ~~
• Highlight - Wrap selection with ==
• Subscript - Wrap selection with ~
• Superscript - Wrap selection with ^
• Inline code - Wrap selection with backticks
• Link - Convert selection to a markdown link
• Bullet list - Convert selected lines to a bulleted list
• Numbered list - Convert selected lines to a numbered list
• Task list - Convert selected lines to a task/checkbox list

Formatting commands are disabled in Preview mode because the Markdown source is hidden.

Automation

VS command URL scheme support

The markdown editor now supports executing Visual Studio commands directly from links in the preview window using the vscmd:// URL scheme.

Example usage:

[Code Search](vscmd://Edit.GoToAll)
[Solution Explorer](vscmd://View.SolutionExplorer)
[Build Solution](vscmd://Build.BuildSolution)

When you click these links in the preview window, the corresponding Visual Studio commands will be executed. A status message will show the result of the command execution.

Custom styles and template

You can provide your own .CSS and HTML templates used to render the preview window. The extension will look for the files md-styles.css and md-template.html in the same folder and any parent folder. If one or both of these files are found, they are being applied in the preview.

The HTML template must contain the string [content] which is where the rendered markdown will be injected.

You have to refresh the preview window after making changes to the custom CSS and HTML file. You can do that from the markdown editor context menu or by hitting Ctrl+Alt+R.

HTML generation in Solution Explorer

Right-click a markdown file in Solution Explorer and select Generate HTML file to enable automatic HTML output.

• The extension generates a sibling .html file from the markdown content.
• The generated file is nested under the markdown file in Solution Explorer.
• On subsequent saves of the markdown file, the .html file is regenerated automatically.
• Run the command again to disable this behavior and remove the generated file.

Automatic regeneration requires a project that supports nesting the generated HTML under the markdown file using DependentUpon metadata. Files in solution folders, loose files, and Open Folder workspaces do not enable regeneration merely by having a sibling .html file. Add the markdown file to a supported project (including a shared project) and run Generate HTML file there. For unsupported items, the command can generate a one-time HTML snapshot, but saves will not update it.

Context menu

Right-click anywhere in the markdown document to access the Markdown submenu with common tasks, such as toggling the preview window scroll sync, see Markdown references, and getting to the settings dialog.

Settings

Control the settings for this extension under Tools -> Options -> Text Editor -> Markdown

Setting	Description
Open documents with preview	Opens Markdown documents in Split mode when enabled, or Source mode when disabled
Enable scroll sync	Synchronizes scrolling between the editor and preview
Preview window position	Choose between right-side or bottom placement
Preview window width/height	Set the size of the preview pane
Enable table sorting	Allows double-clicking table headers to sort columns (underlines headers when enabled)
Optimize images on paste	Automatically optimizes pasted images using Image Optimizer (requires Image Optimizer extension)
Show trailing whitespace	Displays dots for trailing double-spaces (soft line breaks) in the editor

Community Feature Requests

This extension addresses several popular feature requests from the Visual Studio Developer Community:

• Mermaid extension files not supported
• Improved Markdown Rendering in Visual Studio
• Split markdown preview horizontally
• Support for Cross-Document Anchor Links
• Markdown preview does not show math formulas
• Support Syntax Highlighting in Markdown

How can I help?

If you enjoy using the extension, please give it a ★★★★★ rating on the Visual Studio Marketplace.

Should you encounter bugs or if you have feature requests, head on over to the GitHub repo to open an issue if one doesn't already exist.

Pull requests are also very welcome, since I can't always get around to fixing all bugs myself. This is a personal passion project, so my time is limited.

Another way to help out is to sponsor me on GitHub.

Development

NuGet versions are maintained in Directory.Packages.props. Build the solution once to restore packages, then check formatting with the same command used in CI:

dotnet format MarkdownEditor2022.slnx --verify-no-changes --no-restore

To run this formatting check before each commit, configure Git to use the local .githooks folder:

git config core.hooksPath .githooks

The hook checks formatting only; run tests separately as described below.

Running tests

Build the solution on Windows using Visual Studio with the extension development tools and .NET Framework 4.8 targeting pack installed. Tests also require Node.js 22 or newer on PATH and the Microsoft Edge WebView2 Evergreen Runtime.

Run the tests from Test Explorer, or from the repository root after building:

dotnet test test\MarkdownEditor2022.UnitTests\MarkdownEditor2022.UnitTests.csproj -c Debug --no-build

The normal MSTest run also executes test\preview-content-script.test.cjs through node --test; no npm install is needed. These behavioral tests use the production src\Margin\preview-content.js asset. Real WebView2 tests exercise the same script with the bundled Prism, Mermaid, and MathJax libraries, covering lazy startup, unchanged-node reuse, superseded updates/undo, and MathJax cleanup. Each browser test uses an isolated profile and disposes its browser before removing that profile. Missing prerequisites fail the tests rather than silently skipping them. CI provisions Node.js and WebView2 and runs these tests through the same dotnet test command.

Browser test output includes render timings and retained MathItem counts. Timings include browser IPC and test polling, not Visual Studio typing-to-paint latency. These tests do not replace profiling the installed extension during a long editing session: verify colorization while typing, edits and undo in a large mixed-content document, and retained managed/native memory after repeatedly opening and closing editors. DOM reuse currently matches exact block markup, so changes to line-marker IDs can recreate otherwise unchanged blocks.

For preview-host changes, also test the installed extension in Visual Studio: repeatedly detach and redock a Markdown document, switch between Source, Split, and Preview (including moving the window while in Source), and click between the floating preview and another document to verify activation. Close a document while its preview initializes and verify that inactive previews do not steal focus.