Mermaid viewer vscode options, compared

A mermaid viewer vscode setup is any way to look at a Mermaid diagram while you're in VS Code, or while you're checking the same file from VS Code. There are three I actually use. The built-in Markdown preview, the "Markdown Preview Mermaid Support" extension when that preview shows a code block, and a browser editor when I want the picture to update as I type and I want an export. This page compares those ways of viewing. It is not the settings walkthrough. The Mermaid in VS Code guide owns the install steps, and preview settings owns the knobs.

I split them because I kept writing one doc that tried to be both, and it turned into a tour of the command palette. People who already have a preview don't need the tour. They need to know which viewer is lying to them, and which one is simply looking at a different copy of the file.

Three ways to look at the same fence

All three can show the same text. They don't show it on the same schedule, and they don't fail the same way.

The built-in preview is part of recent VS Code. You open a .md file, you run the Markdown preview, and a fence with the info string mermaid becomes a diagram if that VS Code build knows how. Older installs show the fence as styled code. Nothing is "wrong" with the diagram yet. The preview never tried to draw it.

"Markdown Preview Mermaid Support" is an extension that teaches that same preview how to draw the fence. I am not going to quote a download count, a star rating, or an extension id. Those numbers move, and I don't want a wrong id in a doc that people copy into the marketplace search. The name is enough to find it. Its job is the preview. It does not give you a separate design surface, and it does not turn .md files into something other than Markdown.

A browser editor is outside VS Code. You paste the fence, or the diagram source, into a page that renders as you type. That's the one I use when I'm still moving nodes and when I need a PNG. VS Code's preview is a glance. The browser is the workbench. Pretending one tool does both is how you sit there saving the file every two seconds and calling it a workflow.

The Markdown fence rules apply to all three. Lowercase mermaid, one diagram keyword per fence, a blank line before the fence if the previous line is a paragraph. A viewer that "doesn't work" is sometimes a fence that isn't a fence. Check the text before you change tools. I have switched viewers twice to fix a missing closing backtick.

The built-in preview on a recent VS Code

Open the file you mean to preview. That sounds obvious, and I still preview the wrong tab. The command is Markdown: Open Preview, or Markdown: Open Preview to the Side if you want the source to stay visible. On a recent build, a legal fence draws. On an older build, you get the code block described above.

The preview follows the preview's own refresh. Saving, or reloading the pane, is the moment to look. Typing a node and watching the pane is a different product. I assumed the built-in preview was broken because a new edge didn't appear. The file was unsaved. The pane was dutifully showing the saved version, which is what a reviewer will also see if you forget to save before you commit. The lag is annoying. It is also a decent guard against reviewing unsaved fiction.

Syntax errors, when the preview is actually rendering, show up as Mermaid's parse message. The editor tab may not underline the fence, because the language service treats it as Markdown. Trust the pane. If the pane shows code and no error, you are not looking at a syntax problem. You are looking at a preview that isn't rendering Mermaid. That's the fork between "fix the line" and "install the extension or use a browser."

The built-in preview is the right viewer when you want to know what a stock VS Code will do with the README. It is the wrong viewer when you want export. It doesn't hand you a PNG. Screenshots of the pane are how diagrams get cropped and then treated as the source of truth. I have been that screenshot. The file on disk had two more nodes than the image in the ticket.

The extension, when the fence stays code

Install "Markdown Preview Mermaid Support" from the extension view when the built-in preview shows your fence as code and you want the picture inside VS Code. Reload if it asks. Reopen the preview. The same command as before. You didn't grow a new preview. You taught the existing one a trick.

If the fence still shows as code, check the info string and check that you reopened the preview after the install. I have enabled an extension and kept staring at the old pane, which never reloaded. Also check you don't have two previews: the Markdown preview, and some other extension's preview with a similar icon. Look at the tab title. I once compared a diagram to itself across two panes and concluded the syntax was nondeterministic. It was two files.

The extension vendors its own Mermaid build, and VS Code vendors one too when the built-in support is present. On a build that already draws Mermaid, adding the extension can mean two implementations in one editor. They can disagree on a newer diagram type. If the built-in preview already draws your flowcharts, I wouldn't install the extension "to be safe." Extra renderers aren't safety. They're a second opinion you didn't schedule. Add it when the built-in path shows code. Leave it off when the built-in path works.

Don't read marketplace rankings into any of this. A popular extension can still be the wrong one for a build that already has the feature, and a quiet extension can be fine. The test is the probe fence, not the badge. Here's the probe I use. One decision, one loop back. If this won't draw, a larger chart won't draw either.

flowchart TD
  open[Open the Markdown file] --> prev[Open the preview]
  prev --> drawn{Boxes or code?}
  drawn -->|Boxes| edit[Edit the file]
  drawn -->|Code| ext[Try Markdown Preview Mermaid Support]
  ext --> prev
  edit --> save[Save]
  save --> prev

The loop from save back to prev is the behavior I want the team to expect. The extension does not turn that loop into a live update. You still save, or you still reload. If someone on the team tells you the extension previews "live," ask them what they mean. Often they mean the preview refreshed quickly after save. That's good. It isn't the same as the picture tracking the cursor.

The probe also keeps people from installing three extensions. ext points back at the preview, not at a list. One extension with the name above. If that one doesn't draw the probe, stop installing. Take the fence to a browser and find out whether the text is valid.

A browser editor when you want live updates and export

Paste the fence into a browser editor when you're restructuring the chart, not when you're checking the README. The editor is the one I use. It opens with no signup. The preview is live, so an illegal line fails while the cursor is still on it. That loop is shorter than save-and-glance, and the shorter loop is why I design there and check in VS Code.

Export is the other reason to leave the preview. VS Code's panes don't apply MermaidViewer's plan limits, because they aren't exporting through it. When I do want a file from the editor, the rules are plain. PNG exists on every plan. Free PNG is 1x and carries a watermark. Starter is $6.99 a month and exports watermark-free PNG up to 4x. JPG, SVG, and PDF are Pro-only, and Pro is $11.99 a month. Free includes 5 AI uses in total, for generate, edit, and fix. I mention the numbers because "just export an SVG" is the kind of instruction that fails on a free account, and then someone screenshots the pane anyway.

The PNG converter is the direct path when the picture is the thing a ticket needs. Use it after the chart has stopped changing. Exporting every intermediate version is how you end up with three PNGs and no memory of which source they came from. I name the PNG after the heading in the Markdown file, and I commit the Markdown, not a gallery.

A Markdown Mermaid viewer is the middle step when you don't want a full editing session. Paste the fence, confirm it renders, go back to VS Code. I use it to separate "the syntax is bad" from "this VS Code won't draw it." If the viewer draws the probe and VS Code shows code, the file is fine. Change the viewer, not the arrows.

AI fix is useful on a parse error you can't see. It is not a reason to skip reading the result. Five uses on a free account go quickly if you ask it to restyle a chart that's already valid. Spend them on fences that won't parse. Then bring the source back into the .md file and let the VS Code preview confirm what a teammate's editor might do.

What each viewer is bad at

The built-in preview is bad at older VS Code, bad at export, and bad at telling you the file is unsaved. It's good at being the default. Most readers on your team will have this or nothing.

The extension is bad at being a second Mermaid on a build that already has one, and bad at any workflow that needs a file format other than "look at the preview." It's good at the specific case where the fence stays code. That's a smaller job than the marketplace listing implies, and the smaller job is the one I want.

The browser editor is bad at being the repo. If you only paste, the .md file drifts. I've closed the laptop with the fixed diagram in a tab and the broken one committed. The habit that prevents that is dull: paste back, save, preview once in VS Code, then commit. The browser is also a different Mermaid build from the one VS Code bundles. A diagram that needs a very new type can succeed in the browser and fail in the preview. Believe the preview for "what will our IDE show," and believe the host you ship to for "what will readers see." How rendering works is the longer version of that chain. Viewing diagrams online is the case where there is no VS Code at all.

None of the three know what IntelliJ will do. IntelliJ's Markdown preview is a different plugin with its own setting search. Don't write a VS Code extension name into a JetBrains setup doc. I did, in a shared wiki, and two people installed unrelated plugins. The fence was never the problem.

A diagram of the choice, not of the product

The probe flowchart is the editing loop. This one is the choice between viewers, which is a different question and shouldn't be stuffed into the same picture. I tried. The nodes became a policy document.

flowchart LR
  need{What do you need?}
  need -->|Glance at the README| builtin[Built-in preview]
  need -->|Fence shows as code| support[Markdown Preview Mermaid Support]
  need -->|Live edits or a PNG| browser[Browser editor]
  builtin --> file[The Markdown file stays the source]
  support --> file
  browser --> file

All three arrows end at the file. That's the opinion I care about. Viewers are disposable. The fence in the repo is the diagram. A PNG exported from the browser is a snapshot for someone who can't render Mermaid. It is not a reason to delete the fence. I keep the snapshot in the ticket and the fence in git. When they disagree, git wins and the snapshot gets replaced.

need is a diamond with three outs. Mermaid will layout that awkwardly sometimes. Awkward is fine. Don't merge "live edits" and "glance" into one node to make the layout calmer. They are different needs, and merging them is how a team standardizes on the preview and then complains it isn't live.

Pick a viewer for the job in front of you

If you're editing a README and the preview already draws, stay in VS Code and save before you look. If the preview shows code, install "Markdown Preview Mermaid Support" and reopen the preview. If you're redesigning the chart or you need a PNG, SVG, or PDF, leave VS Code for that session and come back with the source.

Use the editor for that session. Paste the fence, fix it while it updates live, export only if something outside git needs a picture, and put the text back in the file. Then open the preview once more. The last look should be the viewer your teammates actually have, not the one that was nicest to design in.