How to Preview Mermaid Diagrams in VS Code

VS Code can render Mermaid diagrams inside its Markdown preview, so you can edit the fenced source and inspect the diagram beside the rest of the document. This is an editor workflow: it helps you iterate locally, but the final README, documentation site, or shared page still needs its own compatibility check.

Current VS Code documentation describes Mermaid rendering as part of the built-in Markdown preview. Older VS Code releases relied on the Markdown Preview Mermaid Support extension; that extension is now deprecated because its functionality was merged into VS Code 1.121.

Open the Markdown Preview

Open a .md file, then run Markdown: Open Preview to the Side from the Command Palette. Keeping source and preview side by side makes syntax changes easy to compare.

Start with a minimal fenced block:

The fence must be labeled mermaid. A text, markdown, or unlabeled fence intentionally displays source instead of rendering a diagram.

Built-In Support Versus the Older Extension

If you use VS Code 1.121 or newer, start with the built-in preview rather than installing the deprecated Mermaid-preview extension. If an organization pins an older VS Code release, its existing extension setup may still provide Mermaid support, but upgrading the editor gives you the maintained path.

After an upgrade, disable redundant Markdown-preview extensions while troubleshooting. Multiple extensions can transform the same preview, contribute scripts or styles, and make it difficult to identify which renderer produced an error.

Why Mermaid Appears as Raw Code

If the preview shows a fenced code block rather than a diagram, check:

1. The file is recognized as Markdown.
2. You opened the rendered Markdown preview, not another text editor group.
3. The fence begins with exactly three backticks followed by mermaid.
4. The closing fence is present.
5. VS Code is current enough to include built-in Mermaid support.
6. Another Markdown extension is not replacing or interfering with the preview.

Test with the minimal flowchart above. If it works, Mermaid is enabled and the original diagram needs syntax or version debugging.

Preview Security Settings

VS Code restricts Markdown-preview content for security reasons. Its Strict setting blocks scripts and insecure remote resources, and the editor recommends keeping Strict enabled unless you trust the workspace and have a specific reason to loosen it.

If remote images or custom preview resources are blocked, use Markdown: Change preview security settings and inspect the warning shown by the preview. Do not disable security merely to repair ordinary Mermaid syntax: a basic fenced Mermaid diagram should not require untrusted remote scripts in current built-in support.

Preview security applies across the workspace. Treat Markdown from an unfamiliar repository as untrusted content even when it looks like documentation.

When the Diagram Reports a Parse Error

Raw code and a Mermaid error are different failures. An error means the preview found the mermaid fence and attempted to parse it.

Reduce the diagram:

1. Keep the diagram declaration and two nodes.
2. Remove custom frontmatter and initialization directives.
3. Shorten or quote labels containing punctuation.
4. Restore subgraphs, edges, and configuration one piece at a time.
5. Compare the Mermaid version used by the publishing destination.

Use the Mermaid Quick Fix guide for malformed connectors and labels. Use the Mermaid version-compatibility guide when the same source works in one renderer but not another.

Large Diagram Navigation

Current VS Code Mermaid preview supports navigation controls for large diagrams, including zooming, panning, and resetting the view. This helps with architecture diagrams that cannot remain legible when shrunk to the width of an editor column.

Navigation does not change the document source. Before publishing, also check how the destination handles large diagrams: a README or static page may use different controls, dimensions, or overflow rules.

Theme and Layout Differences

The VS Code preview follows editor theme and preview styling. A diagram can therefore use different colors or occupy different space after it is published elsewhere. Avoid relying on color alone to distinguish paths, and keep labels readable in both light and dark contexts.

For layout problems:

• Use flowchart TB for narrow preview columns.
• Use flowchart LR for short pipelines.
• Shorten node labels before forcing dimensions.
• Split very large diagrams into overview and detail views.

The Mermaid flowchart-direction guide explains TB, TD, LR, RL, BT, and subgraph direction without mixing that syntax into editor setup.

Verify the Final Markdown Document

VS Code preview proves that the local editor can render the source. It does not prove that GitHub, a documentation generator, or a recipient's viewer uses the same Mermaid version.

Before sharing:

1. Open the final destination or a representative renderer.
2. Check every diagram, not just the first one.
3. Verify links, tables, math, and images around the diagrams.
4. Test large diagrams at a narrow width.
5. Keep explanatory prose meaningful if diagram rendering is unavailable.

You can open the complete Markdown in mdview.io for a browser-based document check after the VS Code editing loop.

VS Code Mermaid FAQ

Do I need a Mermaid extension in current VS Code?

VS Code documentation says Mermaid rendering is built into the Markdown preview. The former Markdown Preview Mermaid Support extension is deprecated after being merged into VS Code 1.121.

Why does Mermaid work in VS Code but fail on GitHub?

The platforms may use different Mermaid releases, configuration, or security behavior. Reduce the diagram and compare the feature that first fails.

Does VS Code preview use the same output as mdview.io?

No. Both can render Mermaid inside Markdown, but each controls its own Mermaid version, styles, page layout, and navigation behavior.