VSCode mermaid preview settings that change the picture

If you are hunting vscode mermaid preview settings, start with the preview pane and a search box, not with a settings id you memorized from a blog. Recent vscode releases render a mermaid fence in the built-in Markdown preview. Older installs show that fence as a code block until you add the extension "Markdown Preview Mermaid Support". The preview updates when you save, not on every keystroke. A security level on the Markdown preview can blank a diagram that is syntactically fine. Those are the behaviors. The extension-shopping version of this topic lives elsewhere. This page is how the preview acts once you have a file open.

Visual Studio Code is the editor I mean by vscode. The fence is three backticks, the word mermaid, the diagram, and three backticks again. You edit the text in the buffer. You look at the picture in the preview. Those stay separate, which surprises people coming from a live diagram tool. The Mermaid in vscode guide walks the install and the first file. I am going to talk about what the preview does after that, and which searches are worth typing.

What a recent install draws

Open a .md file. Run Markdown: Open Preview, or Markdown: Open Preview to the Side if you want the source to stay visible. On a recent vscode, the built-in Markdown renderer includes Mermaid, and the fence becomes a picture in that pane. The text buffer does not turn into boxes. You are still editing text. I prefer Preview to the Side for the first hour, because a preview pointed at the wrong file will sit there looking innocent while you edit. The tab title should match the file you think you are changing.

The preview's Mermaid build is the one that vscode release vendors. Updating vscode can change how a fence renders. Staying on an old release means the built-in path is absent and the extension is the renderer, with its own bundled build. Three previews of one file can disagree: the extension, the built-in preview, and the website you will publish to. When they disagree, believe the host you ship to. vscode is where the file lives. GitHub or GitLab is where the reader is. The Mermaid in Markdown guide is the fence those hosts share. A preview that only works inside vscode is a local convenience, and I have shipped a diagram that "looked fine" and failed in the pull request because I never opened the pull request.

Syntax errors show up as Mermaid's message in the preview pane. The buffer may look happy, because the fence is ordinary Markdown and the language service is not always a Mermaid parser. Trust the preview's error. If the message is vague, paste the inside of the fence into the editor, where the failing line is easier to see, or follow the syntax errors guide. The editor can also fix a diagram with AI. The preview will not rewrite the file for you. It only draws.

Older installs and one extension name

On an older vscode, the same preview command shows a styled code block. The words are there. The boxes are not. Install the extension named "Markdown Preview Mermaid Support" from the extension view, reload if it asks, and open the preview again. The name matters. Several extensions mention Mermaid, and I have installed a highlighter that made the fence pretty and still did not draw it. The one that draws the preview is "Markdown Preview Mermaid Support". Its job is the preview pane. It does not add a special file type, and it does not replace the fence with a drawing inside the buffer.

After you update vscode, you can end up with both the built-in renderer and the extension. That is allowed, and it is also a source of "which picture am I looking at?" If the built-in preview already draws the fence, I disable the extension on that machine so I am not comparing two Mermaids by accident. If the built-in preview does not draw it, the extension stays. I do not keep a private matrix of version numbers in this page. Open the preview. If you see boxes, you are done. If you see source, install the extension with that full name and look again.

The markdown mermaid viewer is a different surface, a page in the browser for a fence you paste. I use it when I do not want to open a repo, or when I am checking a snippet from a ticket. It is not a vscode setting. It is the escape hatch when the preview pane and I are having two conversations.

Search Settings for mermaid

I am not going to give you a settings key to memorize. Keys get renamed, and a wrong key in a doc becomes cargo cult. Open Settings and search for mermaid. Read the matches that vscode and your extensions actually expose on this install. What you see is the list. What a stranger's screenshot showed last year is a rumor.

Search hits I expect, and that I still re-read rather than assume:

• Anything that mentions the Markdown preview and Mermaid together, including a toggle an extension added.
• The preview's behavior for when it refreshes. I want "on save" to be an explicit choice in my head even if the control is worded differently.
• Theme-related Mermaid options, if the extension added any. Default colors survive a theme change better than a fill you copied from a white-background tutorial.

If the search returns nothing, you are probably on a build where Mermaid is simply part of the preview and there is no separate switch. That is a fine outcome. Do not invent a key in settings.json to feel thorough. An unknown key does nothing, or it does something you will forget you set. The preview pane is the test. A JSON edit is not.

Workspace settings and user settings can both match the search. The workspace one wins for this folder. I have "fixed" a diagram by editing the wrong scope and then opened the repo on another machine where the user setting was absent. Check the scope label on the setting you changed. If you need the team to share it, the workspace setting belongs in the repo, and even then I would rather the diagram render on defaults. A settings dependency is a setup step every new hire will miss.

The security level can blank the picture

The Markdown preview has a security level. A strict level can refuse the script the preview uses to draw, and the pane stays blank or shows the source while the fence is valid. This is the setting people miss because searching for mermaid does not always surface it. It is a Markdown preview control, not a Mermaid control. If the diagram parses in the editor and the vscode preview is an empty gap, look at the preview's security warning or search Settings for the Markdown preview security level. I am still not printing a key. The wording on your install is the wording you should click.

Raise the level only as far as you need to see your own files, and know what you are allowing. A preview that executes more is a preview that can do more with a hostile fence. I will loosen it for a repo I trust so I can see the diagram. I will not loosen it as a global default on a machine that opens random Markdown from the internet. If the security warning is the thing on screen, read it. Dismissing it and then reinstalling the extension is the long way around.

A blank preview has other causes, and I check them before I touch security. Wrong file in the preview tab. Fence info string missing. Extension not installed on an old vscode. Diagram type too new for the bundled Mermaid. Security is the cause that feels like a bug because the same file rendered yesterday, before a settings sync "helped."

Save, then look

The preview updates on save, not on every keystroke. Type a node, watch the pane, and it will sit still. That is the schedule. Save, then look. If you want the picture to follow the cursor, keep the editor open and paste back when the branch is right. The editor's preview is live. vscode is the file you will commit. I use both, and I stop expecting one to behave like the other.

Autosave changes the feel. If vscode saves after a delay, the preview will catch up on that delay, which is still not "every key." I have turned autosave off for a docs folder because a half-written fence kept flashing an error in the preview while I typed the next node. Manual save makes the error appear when I think the fence is whole. Either habit works if you know which one you have. The failure is believing the preview is broken because it did not twitch at the third character of a label.

A sequence in the same file is a second fence, not a second mode. Save once and both should redraw. If only one updates, you are looking at a preview of a different buffer, or the second fence is missing its info string. Here is the pair I use as a smoke test. They are small on purpose. A smoke test that is also your architecture diagram will teach you nothing when it fails, because you will not know whether the failure is the preview or the chart.

flowchart LR
  write[Write the fence] --> save[Save the file]
  save --> look[Read the preview]
  look --> ok{"Picture updated?"}
  ok -->|Yes| commit[Commit the Markdown]
  ok -->|No| save

The loop back to save is the behavior. Another keystroke is not a step on this chart. If this fence fails to draw, the graph is not the puzzle. Check the vscode version, the extension name, the info string, and the security level, in that order.

sequenceDiagram
  actor Author
  participant VS as vscode
  participant Prev as Preview
  Author->>VS: Edit the fence
  Author->>VS: Save
  VS->>Prev: Refresh the picture
  Prev-->>Author: Show the diagram

That sequence is the whole timing model. Edit, save, refresh, look. There is no arrow for "preview notices a keystroke." I want that absence to be obvious. The how to render Mermaid note covers the browser and the CLI, which do have different timing. Do not import their expectations into this pane.

Settings I refuse to memorize

I refuse a personal cheat sheet of JSON keys for Mermaid. Search Settings for mermaid on the machine in front of you, change one thing, save a file, and see the preview move or not move. Revert if you cannot describe what changed. Stacking three extension toggles because a thread said they were required is how a laptop becomes a snowflake. The next clone of the repo will not have your snowflake, and the diagram should still render.

Font and zoom belong to the preview pane's own controls and to vscode's zoom, not to a Mermaid-specific secret. If the labels are too small, zoom the editor. If the labels are too small because the node is a paragraph, shorten the node. A settings change will not make a sentence fit in a box. Direction TD often fits the side preview better than LR, because the pane is a column. That is a diagram edit. It belongs in the file, where the reviewer can see it.

Color fills copied from a screenshot are the other false setting. They are in the fence, as classDef or a style line, and they break when the preview is dark. Delete them before you go hunting for a theme key. "Approved" in the label works in both themes. A pale green rectangle does not. I check the preview in the theme I actually use, then I switch the theme once. If a fill only works in one, the fill is the bug.

The Mermaid viewer in vscode comparison is about choosing tools. The IntelliJ markdown Mermaid note and the Typora Mermaid note are other editors with other previews. Their settings screens are not this search box. A tip that says "set the preview to strict" might be meaningful there and blank your diagram here. Apply their advice on their tool.

When the preview is the wrong loop

The preview is the right loop for a doc you are about to commit. It is the wrong loop for designing a twenty-node chart, for a host that is not Markdown, and for a teammate who does not use vscode. Design the chart where the preview is live. Confirm the fence here, on save, in the file that will be reviewed. If the security level is in the way and you cannot loosen it, export or use the browser viewer rather than weakening a global setting you will forget.

Keep a live browser preview beside vscode when the save-to-see loop starts to grate. Paste back, save, and let the built-in preview confirm the bytes on disk. Search Settings for mermaid if something on this install needs a toggle. Install "Markdown Preview Mermaid Support" only when the built-in preview leaves the fence as code. Leave the security level strict enough that you would still open a stranger's repository. The picture should appear after a save. If it appears only after a ritual of keys you found on a gist, the ritual is the thing to delete. Open the editor for the keystroke-by-keystroke pass, then save the file and trust the vscode pane.