Coffee

Mermaid diagrams in Markdown

By Pedro Thomaz, who makes Coffee. 4 min read. Read as Markdown

Checked November 2026 against GitHub's docs on diagrams, the Mermaid docs, Mermaid CLI and VS Code's Markdown docs. Coffee isn't affiliated with any of them.

Mermaid is a way of describing a diagram in text, and Markdown carries it in a fenced code block. Open the block with three backticks followed by the word mermaid, write the diagram, and close it with three backticks. An app or site that supports Mermaid draws the picture. Anywhere else, the reader sees the text, which is short enough to make sense on its own.

Why write diagrams as text

A diagram drawn in a graphics app is a separate file you have to export, place and redraw when something changes. A Mermaid diagram lives in the note, beside the writing it explains. Changing a step means editing a line. It works with version control, search and AI tools like any other text, and nothing is lost if the app you use now stops drawing it.

The trade-off is control. Mermaid lays the diagram out for you, so you describe what connects to what, not where each box sits.

Flowcharts

A flowchart starts with flowchart (or the older graph) and a direction: TD for top down, LR for left to right. Then one line per connection:

flowchart LR
    A[Draft] --> B{Approved?}
    B -->|Yes| C[Publish]
    B -->|No| A

Inside the block, that draws three arrows between three shapes. The letters are names you use to refer to each shape. The brackets set the shape: [ ] for a box, { } for a diamond, ( ) for rounded corners. --> draws an arrow, and text between pipes, as in |Yes|, labels it.

Pie charts

A pie chart takes a title and one line per slice, with the label in quotes and a number after a colon:

pie title Where the week went
    "Writing" : 18
    "Meetings" : 9
    "Email" : 6
    "Research" : 7

The numbers don't have to add up to 100. Mermaid works out each slice's share of the total.

Sequence diagrams

A sequence diagram shows messages passing between people or systems, top to bottom in time order:

sequenceDiagram
    Writer->>Editor: Here's the draft
    Editor-->>Writer: Two comments
    Writer->>Editor: Fixed, please check

->> is a solid arrow and -->> a dashed one, often used for replies. Each name becomes a column, in the order it first appears.

Mermaid has many more kinds, including Gantt charts, class, state and entity relationship diagrams, and mind maps. The Mermaid docs cover each one, and the Mermaid Live Editor lets you try the syntax in a browser.

Where Mermaid renders

  • GitHub draws a mermaid code block as a diagram in Markdown files, issues, discussions, pull requests and wikis. It notes that what's supported depends on its Mermaid version, and that putting info in a block shows which version that is.
  • VS Code's built-in preview renders Mermaid in mermaid code blocks.
  • Many Markdown editors and note apps draw it, sometimes only for some diagram kinds or after you turn it on.
  • Plain text editors and most email clients show the code.

Because support varies, write the code so it reads well as text too: short, clear labels and one connection per line.

Exporting a diagram

If you need the diagram as an image, for a slide or a document that can't run Mermaid, you have a few routes:

  • Mermaid CLI turns a diagram file into SVG or PNG from Terminal. Install it with npm install -g @mermaid-js/mermaid-cli, then run mmdc -i diagram.mmd -o diagram.svg. Give it a Markdown file instead and it renders each mermaid block and writes a copy of the file that links to the images.
  • An editor that exports with the diagram drawn, as a PDF, HTML page or Word file.
  • A screenshot, which is quick and fine for something informal.

SVG stays sharp at any size, so prefer it to PNG where the destination accepts it.

In Coffee

Coffee draws three kinds of Mermaid diagram: flowcharts written with flowchart or graph, pie charts, and sequence diagrams. The picture appears under the code block as you type, drawn by Coffee itself, and it's included when you export to PDF, HTML, Word or EPUB, so the diagram reaches a PDF or an e-book without a separate image.

Other kinds, such as Gantt charts and class or state diagrams, stay as code in Coffee. That's worth knowing before you rely on one. The file keeps exactly what you wrote either way, so GitHub or another tool can still draw those kinds later.

Coffee also draws $$ maths blocks as formulas. See writing maths in Markdown.

Questions

How do I add a Mermaid diagram to Markdown?

Put the diagram in a fenced code block whose opening line is three backticks and the word mermaid. Apps and sites that support Mermaid draw it, and others show the code.

Does GitHub support Mermaid?

Yes. GitHub draws Mermaid code blocks in Markdown files, issues, discussions, pull requests and wikis. Which syntax works depends on the Mermaid version GitHub uses.

How do I export a Mermaid diagram as an image?

Mermaid CLI converts a diagram to SVG or PNG from Terminal. An editor that draws Mermaid can also include it in a PDF, HTML or Word export.

Which Mermaid diagrams does Coffee draw?

Flowcharts, pie charts and sequence diagrams, in the editor and in PDF, HTML, Word and EPUB exports. Other kinds stay as code.