Mermaid in VS Code: Preview, Extensions, and Export

VS Code's built-in Markdown preview does not render Mermaid. Open a README with a ```mermaid block, press Ctrl/Cmd+Shift+V, and the block appears as plain text. The fix is a small extension, and once it is installed the workflow of writing diagrams next to code becomes quick.

This post covers the preview extension, standalone .mmd files, syntax highlighting, three export routes, and how to handle diagrams that an AI assistant writes into your Markdown.

Render Mermaid in the Markdown preview

1. Open the Extensions view (Ctrl/Cmd+Shift+X) and search for Markdown Preview Mermaid Support by Matt Bierner. It is the long-standing default choice and has no configuration.
2. Install it. No reload is needed in current VS Code builds.
3. Open any Markdown file with a mermaid fence and run Markdown: Open Preview to the Side (Ctrl/Cmd+K V).

## Request flow

```mermaid
sequenceDiagram
    participant C as Client
    participant S as Server
    C->>S: GET /items
    S-->>C: 200 OK, JSON list
```

The preview follows your VS Code color theme: a dark editor theme gives a dark diagram. The extension tracks a recent Mermaid release, so diagram types that render on GitHub also render here. It does not add export or error line numbers; a failing diagram shows a short message in the preview pane.

Standalone .mmd files

Diagrams that are shared between several documents, or rendered at build time, usually live in their own files with a .mmd or .mermaid extension. The Markdown preview extension ignores these because they are not Markdown. Two options:

• Install a dedicated Mermaid editor extension. Search the Marketplace for "Mermaid preview" and pick one with recent updates; the official Mermaid Chart extension and several community extensions provide a side panel that re-renders on save.
• Keep VS Code for editing and paste the file into MermanDraw for the preview. The editor marks the failing line, offers one-click fixes for common mistakes, and exports PNG or SVG from the same screen.

Syntax highlighting

Highlighting inside a Markdown fence comes from the Markdown grammar and is minimal by default. The Mermaid-specific extensions register a grammar for .mmd files and for fenced blocks, which colors keywords, arrows, and labels. If a block appears without color after installing an extension, check that the fence language is exactly mermaid in lowercase; Mermaid and mmd do not match.

Export PNG or SVG

Three routes, in order of setup cost:

1. Browser editor. Copy the diagram, paste it into MermanDraw, choose a theme, and download. PNG exports at 2× resolution, SVG keeps text selectable. No install, and the paste strips the Markdown fence lines for you.
2. Extension export. Some Mermaid preview extensions add a "Save as PNG" or "Save as SVG" action in the preview panel. Convenient when you already use one for .mmd files.
3. Command line. The official @mermaid-js/mermaid-cli package renders files headlessly and fits into a build step or a pre-commit hook.

# one-off export, no global install
npx @mermaid-js/mermaid-cli -i diagram.mmd -o diagram.png

# SVG, transparent background, dark theme
npx @mermaid-js/mermaid-cli -i diagram.mmd -o diagram.svg -b transparent -t dark

# every diagram in a Markdown file becomes an image
npx @mermaid-js/mermaid-cli -i README.md -o README.out.md

The last command rewrites a Markdown file, replacing each mermaid fence with an image reference. That is the usual way to publish to a platform that does not render Mermaid itself; the native support list tells you which ones do.

AI-generated Mermaid inside VS Code

GitHub Copilot, Claude, and other assistants in the editor write Mermaid directly into Markdown when asked ("add a sequence diagram of the login flow below this heading"). The output renders on the first try most of the time. When it does not, the causes are repetitive:

• Parentheses or brackets inside an unquoted label, such as A[Click (here)]. Wrap the label in double quotes.
• A second ```mermaid line pasted inside the fence you already had. Delete the inner fence.
• Smart quotes or Unicode arrows copied from a chat window. Replace with straight quotes and -->.
• Mixed grammars: a flowchart that drifts into sequence-diagram arrows half-way through. Ask the assistant to regenerate as one type.

Paste the failing block into MermanDraw and the editor highlights the line from the parser error and, for the first three causes, fixes it with one click. Paste the result back into the file. The AI prompting guide has prompt patterns that avoid these mistakes up front.

flowchart LR
    Edit[Edit diagram.mmd] --> Preview[Preview in VS Code]
    Preview --> OK{Renders?}
    OK -- No --> Fix["Fix the marked line (MermanDraw)"]
    Fix --> Edit
    OK -- Yes --> Export[Export PNG or SVG]
    Export --> Docs[Commit to docs folder]

A workable setup

For most repositories: the Markdown preview extension for READMEs and docs, a docs/diagrams/ folder with .mmd files for anything reused, and mermaid-cli in the docs build when the target needs images. For syntax questions while writing, the sequence, flowchart, and class diagram guides cover the details, and the examples gallery has complete diagrams for architecture and API documentation that drop straight into a repo.

FAQ

Related

• Mermaid in a GitHub README — the same fences render on GitHub without a build step.
• Export Mermaid to PNG and SVG
• Mermaid diagrams in Obsidian