The mermaid format, from .mmd files to fences

The mermaid format question, in the sense that matters when a file won't render, is the difference between a .mmd file and a Markdown fence. A .mmd file is the diagram and nothing else. Its first line is the diagram keyword, not a fence. A Markdown file wraps that same text in backticks and an info string so a docs host knows which paragraphs are diagrams. Mix them up and the converter, or the preview, eats the wrong line first.

I made that mistake by renaming checkout.md to checkout.mmd and leaving the fences in place. The file extension changed. The contents were still a blog post. The tool I pointed at it failed on the first backtick and I blamed Mermaid. The format was the bug. The chart was fine.

A .mmd file is the diagram and nothing else

.mmd is a convention, not a feature of the filesystem. It's a text file whose contents are one Mermaid diagram. Editors and converters started recognizing the suffix so they could guess the language. The suffix doesn't make the text valid. A .mmd file full of meeting notes is still meeting notes.

One diagram per file is the habit that keeps the format honest. The keyword on line one picks the grammar. The lines after it are statements in that grammar. A second keyword doesn't start a second picture. It breaks the first one. If you have two charts, you have two files, or you have a Markdown document with two fences. Don't concatenate .mmd files and hope a blank line splits them. It doesn't.

I name the file after the claim, not after the type. refund-policy.mmd is better than flowchart-1.mmd. The type is already the first line. The name should tell a reviewer what they'll contradict if the arrows are wrong. Numbered files become a junk drawer. I had a folder of those. Opening diagram3.mmd never answered "is this the one production uses."

Comments, the lines that start with %%, are allowed and don't appear in the picture. A title a human should see does not belong in a comment. Put the title in the Markdown that links the file, or in a heading above a fence. A .mmd file has no heading. That's a limitation I accept, because the alternative is sneaking a paragraph above the keyword and breaking every tool that expects the keyword first.

The first line is a keyword

The first meaningful line is flowchart, sequenceDiagram, erDiagram, stateDiagram-v2, or whichever type you're drawing. A direction can sit on that same line: flowchart TD. A blank line above it is harmless. A fence above it is not.

This is a complete .mmd file. If you saved these lines as refund.mmd, a converter that understands the suffix should see flowchart immediately.

flowchart TD
  ask[Refund requested] --> gate{Over 50?}
  gate -->|No| auto[Auto approve]
  gate -->|Yes| mgr[Manager review]

There is no info-string line and no closing fence. Adding either one "so it's more valid" makes it less valid as .mmd. I did that to be safe. Safety was a backtick. The parser then tried to treat the backticks as a node and failed in a way that doesn't mention fences at all. If the error points at line 1 and line 1 is a fence, delete the fence. Don't debug the nodes underneath it yet.

Front matter is the other thing people put above the keyword. A YAML block that sets a theme is a real Mermaid feature in some hosts, and it's also a way to make line 1 not the keyword. I leave it out of .mmd files I expect to pass through more than one tool. The default theme is portable. A theme block that one CLI accepts and an older preview rejects is a format problem disguised as a style problem. The syntax overview is where theme blocks and keywords are catalogued. Use it when you need the block. Don't start there if the file won't even parse. Start by reading line 1.

A UTF-8 BOM, the invisible bytes some editors write at the start of a file, can also steal line 1. The keyword looks correct and the tool says it isn't. I've only hit this moving files from a Windows editor to a CI job. If the keyword looks right and line 1 still fails, recreate the file in the editor that will run it, or strip the BOM. I'm not going to give you a hex dump ritual. Open the file, select all, paste into a new file, save. That fixes it more often than it should.

How that differs from a Markdown fence

A Markdown file is a document. Prose, headings, lists, and then a fence when a diagram should appear. The fence's info string is the word mermaid. The lines inside are exactly the .mmd contents. The fence is packaging. The diagram is the inside.

The same refund chart, as a fence in a .md file, looks like this when you view the source. The rendered page shows the picture, not the backticks.

flowchart TD
  ask[Refund requested] --> gate{Over 50?}
  gate -->|No| auto[Auto approve]
  gate -->|Yes| mgr[Manager review]

If you feed this whole Markdown document to a converter that expects .mmd, you're handing it headings and paragraphs. Some tools are kind and search the file for a fence. Some aren't, and the kind ones still have to guess which fence you meant when there are two. I don't rely on the kindness. If the tool says it wants a Mermaid file, I give it a .mmd file. If the tool is a docs site, I give it Markdown. The Mermaid in Markdown guide is the fence side of that choice. This page is the file-suffix side.

The info string is not optional on the Markdown side. Three backticks with no mermaid are a code block, or on a sloppy renderer a diagram by accident. I write the info string every time. Inside the fence, I still start with the keyword. The info string tells Markdown. The keyword tells Mermaid. They are not substitutes. A fence whose first inner line is a sentence will fail the same way a .mmd file whose first line is a sentence fails.

Indentation differs in a way that bites people who paste. A fence inside a list item is indented, and the closing fence has to line up with the opening one. A .mmd file should not be indented as if it lived in a list. The keyword starts at column zero. I pasted a fenced diagram out of a list into a .mmd file and left four spaces on every line. One viewer tolerated it. The CLI didn't. Column zero is the boring fix.

Opening the file

A .mmd file opens in any text editor, because it is text. VS Code will show it as plain text unless an extension has claimed the suffix. That's fine. You can read a flowchart without syntax colors. Don't install a random extension just to get highlighting. Highlighting doesn't render the picture, and a wrong extension can apply a different grammar and underline legal lines.

To see the picture, paste the file's contents into a renderer. The editor does that with a live preview and no signup. You paste the keyword and the statements. You do not paste a fence around them first. If you copied from Markdown, strip the backticks and the info string before you judge the diagram. I have "fixed" a valid chart by editing the fence that shouldn't have been in the buffer.

GitHub and similar hosts render fences in .md files. They do not all render a raw .mmd file as a picture when you click it in the repo browser. Some show the source, which is actually what you want in review: the diff is the lines. The picture is for humans checking the result. Viewing diagrams online covers browsers when you don't have the file open locally. Turning code into a diagram is the other direction, from a snippet someone pasted in chat toward a real file. A snippet in chat has usually lost its first line or gained a fence. Put the keyword back before you save .mmd.

I keep .mmd files next to the doc that explains them when the diagram is reused in more than one page. docs/diagrams/refund-policy.mmd is the source. The pages include it or duplicate the fence. Duplication drifts. Inclusion depends on the docs tool. If your tool can't include a file, duplicate the fence and write a one-line comment in the Markdown naming the .mmd path as the copy that wins. I skipped that comment once. The two copies disagreed about the fifty-dollar gate for a month.

Turning it into SVG or PNG

Export is a render plus a file format. The source stays .mmd or stays a fence. The SVG or PNG is a result. I commit the source always. I commit the image only when a consumer can't run Mermaid, and I treat the image as stale the moment the source changes.

The export guide is the long version of format choice: vectors versus pixels versus a page. The short version I actually use is: SVG when the picture will be scaled or edited as vectors, PNG when the destination is a ticket, a slide, or a chat app that only accepts images. PDF is a page, and I rarely need it for a single chart.

MermaidViewer's converters follow the plan, and the plan is the part people hear wrong. PNG works on every plan. Free PNG is 1x and has a watermark. Starter is $6.99 a month and can export watermark-free PNG up to 4x. JPG, SVG, and PDF are Pro-only. Pro is $11.99 a month. If you need an SVG and you're on Free or Starter, the converter will not quietly upgrade you. Use the SVG tool when you're on a plan that includes it. Use the PNG tool when a watermarked 1x image is acceptable, or when Starter's larger PNG is what the ticket asked for. I tried to "just grab an SVG real quick" on a free account and wasted the time. The plan said no. The plan was right.

The preview is free either way. You can read the diagram in the editor without exporting. Export when someone who will not open the editor needs a file. Don't export as a backup of the source. An SVG is a miserable thing to diff, and a PNG doesn't diff in any way that shows the arrow you changed. The .mmd diff shows the arrow.

Scale is a PNG problem. A 4x PNG is much larger than 1x, and "larger" is pixels, not a sharper sentence. If the labels are already readable at 1x, the 4x file is just heavier. I attach 1x to tickets unless the image is getting stretched on a retina slide and looks soft. Background matters for PNG more than for SVG. A transparent background pasted into a tool that paints transparency black looks like a broken export. If you're unsure, export on white. The export guide says this at more length. I'm repeating the part I've gotten wrong.

A second diagram belongs in a second file if you're in .mmd land. This one is the same refund policy as a sequence, so a converter isn't asked to hold two keywords in one file. The charge and the review are different actors. The flowchart collapsed them into boxes. The sequence refuses to.

sequenceDiagram
  participant User as User
  participant Shop as Shop
  participant Mgr as Manager
  User->>Shop: Request refund
  alt under 50
    Shop-->>User: Approved
  else 50 or more
    Shop->>Mgr: Ask for review
    Mgr-->>Shop: Decision
    Shop-->>User: Decision
  end

Save that as refund-review.mmd without the fence if a CLI wants a Mermaid file. Keep the fence if this page is the consumer. Don't save one file that starts with flowchart and later contains sequenceDiagram. I tried a "bundle" file. The error was on the second keyword, and I assumed the sequence syntax was illegal. The sequence was fine. The bundle was the format violation.

How a diagram gets rendered is the pipeline from that text to pixels. You don't need the pipeline to export. You need it when the export succeeds and the picture is still wrong, which usually means the text was wrong, or the tool rendered a different file than the one you edited. Check the input path. I've exported refund.mmd while editing refund-review.mmd and published the old policy with confidence.

When the fence is the better artifact

Use Markdown when the diagram needs sentences around it. A .mmd file can't say "over 50 means 50.00 in the currency of the order, tax excluded." That sentence is the difference between two implementations. The fence sits under the sentence, and the sentence sits in the doc reviewers already read. A folder of .mmd files with no prose becomes a gallery nobody checks against the code.

Use .mmd when a tool chain wants a diagram and will reject prose, and when the same chart is included from several docs. Also use it when you want the smallest possible diff. A fence inside a large Markdown file is fine to diff, but a one-screen .mmd file is easier to review on a phone, which is where I end up approving docs changes more often than I admit.

Don't convert back and forth every day. Pick the source. Generate the other shape if you must. If Markdown is the source, generate .mmd by copying the inside of the fence, not by renaming the file. If .mmd is the source, generate the fence by wrapping it, not by adding backticks inside the .mmd file "temporarily." Temporary backticks become the file.

Neither format likes the word end as a node id. In a flowchart it's a footgun. In a sequence diagram end closes alt. Name the last box done if you mean the end of the process. I'm mentioning it here because moving a chart from a fence into .mmd doesn't fix an id that was already illegal. The format change preserves bugs. Read line 1, then read the ids.

Keep the source next to the picture

Store refund-policy.mmd or store the fence. Store the PNG beside it only for a consumer that needs pixels, and name the PNG so it's obvious which source produced it. When the policy changes, edit the keyword file first, preview it, then re-export. The other order is how the image and the source diverge, and the image usually wins the argument because it's the one in the slide.

Open the editor with the .mmd contents, not with a fence wrapped around them, and confirm the first line is the keyword before you export. If you came from Markdown, the backticks stay in the Markdown file. They don't come with you. That split is the whole format. Once it's boring, the diagrams get easier, because you stop debugging the packaging and start arguing about the fifty-dollar gate, which was the actual question.