IntelliJ markdown mermaid preview in JetBrains IDEs

An intellij markdown mermaid preview is a mermaid fence in a Markdown file, drawn by the Markdown plugin inside a JetBrains IDE. Recent IDEs can preview Mermaid in that plugin. The setting name moves between releases. Search settings for Mermaid before you install a random plugin from the marketplace.

I want that sequence to stay in that order, because I did it backwards and lost an hour. I couldn't find a menu called Mermaid, so I installed a plugin a forum post recommended. The bundled Markdown plugin already had the preview. The extra plugin fought with it. Uninstalling was the fix. Searching was the step I skipped.

What the preview is actually for

You edit a .md file in the editor you already use for the repo. A fence that starts with three backticks and mermaid is a diagram, on a build that knows how to draw one. The preview is a pane. It is not a second file, and it does not replace the fence with a picture inside the text buffer. You still edit text. The pane shows what a Markdown host might do with that text.

Open the preview the way you open any Markdown preview in the IDE. I am not going to invent a menu path. JetBrains renames actions, and a path I write today will be wrong on the build you installed last quarter. Use Find Action and look for the Markdown preview. If the fence renders, you're done with setup. If it shows as a styled code block, the next step is settings search, not a plugin.

The preview is a check you run on purpose. It is not a picture that updates on every keystroke. I type a new node and expect the pane to twitch, and it doesn't, and I assume the plugin crashed. It is waiting for a refresh. Save, or hit the preview's reload, then look. If you want the boxes to follow the cursor, that is a different tool. The IDE is where the file lives.

Fence rules are the same ones a GitHub README uses. The info string is lowercase mermaid. The first line inside is a diagram keyword. A blank line between a paragraph and the fence keeps some parsers from gluing the opening line to the previous sentence. The fence rules for Markdown cover that hygiene for files that will also render outside the IDE. Read them once. The preview will not teach them to you. It will just fail.

Search settings before you install anything

Open Settings and type Mermaid into the search box. Don't browse trees. The setting name moves. On one build it's a checkbox under the Markdown plugin. On another the wording changes, or it sits next to a preview option you wouldn't think to open. Search finds it when the name has drifted. Browsing finds it only if you already know this year's label.

If the search returns a Mermaid-related option, that option is the switch for this build. Turn it on if it's off, apply, and reopen the preview. If the search returns nothing, this build's Markdown plugin isn't offering the feature. That's a version fact, not a challenge to solve with the first marketplace hit.

A random plugin is how you get two renderers. I installed one that registered its own preview action. The bundled preview and the plugin preview disagreed about a sequence diagram, and I spent the review meeting arguing about a diagram that parsed in one pane and not the other. The file hadn't changed. The panes had. If you do install something, know why, and know which pane you're looking at. Prefer the bundled Markdown plugin on a recent IDE. That's the one JetBrains is actually shipping.

Recent matters. An old IDE can have a perfectly good Markdown plugin that still has no Mermaid. Updating the IDE is a bigger decision than a diagram, and I won't pretend a preview is a reason to jump major versions on a Friday. If you can't update, paste the fence into a viewer when you need the picture, and keep editing the file in the IDE. The source doesn't care where it was previewed.

PyCharm, WebStorm, GoLand, Rider, and IntelliJ IDEA share a lot of this plugin, and they still don't share a release clock. "It works in IDEA" is not a promise about the PyCharm build your data team pinned. Search settings on the IDE that will open the file. Write the IDE name and build in the pull request if the preview behavior is part of the review. I started doing that after a teammate on an older Toolbox build told me the chart was "just code." It was just code, for them.

A fence that belongs in a README

This is the chart I drop into a service README when the question is "what does the request do after it arrives." It's small on purpose. A preview pane is often half the window, and a 40-node architecture drawing becomes a scrollbar.

flowchart TD
  req[Request arrives] --> auth{Authenticated?}
  auth -->|Yes| load[Load the account]
  auth -->|No| reject[Reject]
  load --> audit[Write the audit row]
  audit --> reply[Return the response]
  reject --> reply

Both paths return a response. The audit row happens only after auth. That join is the kind of thing a paragraph smears. "We reject unauthenticated calls and we write an audit row" can be read as both happening, or as the audit happening first. The chart is blunt. Reject does not pass through the audit node. If your service does audit the rejection, the chart is wrong and you should add the arrow. Don't leave the picture flattering.

Labels stay short because the preview wraps them. "Reject" is enough. "Reject with 401 and do not write an audit row" is a sentence, and it belongs under the fence. I used to stuff the sentence into the node so I wouldn't have to write the paragraph. The node became a column, the diamond drifted, and the preview looked broken when the syntax was fine. The flowchart page is where node shapes and labeled edges are documented. You need it when a decision grows a third label. You don't need it to read this chart.

Save the file and refresh the preview. Read it the way a reviewer will, top to bottom. If the No branch is hard to see, the chart is still right. Making the happy path the only visible path is how READMEs rot. I'd rather a slightly awkward layout than a missing rejection.

The preview is not the artifact

The artifact is the Markdown file. The preview is a local convenience. GitHub, GitLab, a docs site, and a teammate's IDE may each bundle a different Mermaid build. A fence that previews cleanly in your IDEA can fail on the site you ship to, or the other way around. When they disagree, believe the host the reader opens. Use the IDE to edit.

Syntax errors show up in the preview as a parse message, when the preview is trying to render. The text 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 line. If the preview shows the fence as code and shows no error, you don't have a syntax error yet. You have a preview that isn't rendering. Go back to the settings search. I have "fixed" a working chart for twenty minutes because I mistook a disabled preview for a broken node.

Comments inside the fence, lines that start with %%, never appear in the picture. Put them on their own line. A comment glued to the end of a statement is a common way to break a file that looked finished. I do this when I annotate an edge in a hurry. The preview then fails on the edge, and I blame the label.

One fence, one keyword. A second flowchart inside the same fence is not a second figure. It's a parse error that hides the first figure too. Two fences, with a blank line between them, are two figures. The preview will show both if it shows either.

A second chart for the review itself

The README chart is the product behavior. This one is the editing loop, and I keep it in the contributor notes so new people stop installing plugins on day one.

flowchart TD
  open[Open the Markdown file] --> prev[Open the Markdown preview]
  prev --> drawn{Fence drew?}
  drawn -->|Yes| edit[Edit and save]
  drawn -->|No| search[Search settings for Mermaid]
  search --> found{Setting exists?}
  found -->|Yes| enable[Enable it and reopen the preview]
  found -->|No| outside[Preview the fence in a browser editor]
  enable --> edit
  edit --> prev

Read found carefully. "No" does not point at a marketplace. It points out of the IDE. That's deliberate. If the setting isn't there, a random plugin is a guess, and I don't want the contributor notes to recommend a guess. Preview elsewhere, commit the Markdown, and let the IDE stay the editor.

The loop back from edit to prev is the part I forget. I edit three nodes, forget to refresh, and review the old picture. The chart is telling you the preview is a step, not a background process. If your build refreshes on save, the loop is short. If it doesn't, the loop includes a reload action. Either way, look again before you push.

If the same file also gets opened in VS Code, the VS Code guide is the install path over there. VS Code's preview settings are the parallel conversation for the knobs. The behavior isn't the same, and copying a VS Code extension name into a JetBrains plugin search is how the random-plugin problem starts. Viewing diagrams in VS Code compares viewers over there. Don't mix the two setups in one paragraph of a README. Say which editor the steps apply to.

JupyterLab is a third host. A notebook Markdown cell is not this preview. A fence that draws in IDEA can show as code in a notebook, depending on the JupyterLab version. Typora is another preview again. I mention them because people keep a spec in the IDE, a notebook, and a notes app, and then act surprised that three pictures disagree. The text can be identical. The renderers aren't.

When the pane is the wrong place to design

The preview is good at one job: showing you roughly what a Markdown file will look like. It is a poor place to design a chart you're still tearing apart. The refresh lag makes you cautious, and caution makes you leave a wrong arrow in place because rerouting it feels expensive. I've shipped that arrow.

When the chart is still moving, paste it into a live preview, fix the structure, and bring the source back. A browser viewer will render the fence without the IDE's refresh rules. That's the right move for a syntax question. It's the wrong move if you then only save the PNG. The IDE file is what the repo reviews. The PNG is a snapshot for a ticket that can't show Mermaid.

Don't add a theme block to "make it look like the IDE." The preview's colors are the plugin's theme. The website's colors are the website's theme. Hard-coded fills are how a chart becomes unreadable on a dark theme you don't use. Leave the fills alone until a reader can't tell two node types apart, and even then prefer a label over a color.

Subgraphs are the feature that makes a README chart worse if you add them too early. A box around three nodes labeled "Backend" doesn't tell a reader anything the headings didn't say. Add a subgraph when it's a real boundary, like a process or a permission check, and give it an id that isn't a sentence. Close it with end on its own line. That word is the closer. It is not a node. If the last step is called end, name the node finish. I lost a preview to that once, and the error pointed at the line after the chart, which is a miserable place to look.

Leave the IDE when the preview stalls

If search found the setting and the probe fence still won't draw, stop. Reinstalling plugins in a loop will not explain a Mermaid build that rejects one diagram type. Sequence diagrams, ER diagrams, and newer types depend on the version bundled in the plugin. A flowchart can work while a newer type shows an error. That's a version skew, and the fix is to simplify the diagram or preview it somewhere with a newer renderer. It is not to stack plugins.

Copy the fence. Open the editor. It previews live, it doesn't ask you to sign up, and it will tell you if the text is illegal. Paste the corrected source back into the Markdown file, save, and refresh the IDE preview. If the IDE still shows code, you've learned something useful: the syntax is fine and this build's preview isn't going to draw it. Commit the file anyway. The readers who open it on GitHub may see the picture even when your pane doesn't. Say that in the pull request so nobody "fixes" a working fence.