What if you could draw a flowchart by describing it in words, instead of dragging boxes around with a mouse? That’s exactly what Mermaid does. It’s a diagramming syntax that turns plain text inside your Markdown into flowcharts, sequence diagrams, Gantt charts and more — rendered automatically. This guide shows how it works.

For the rest of the language, see the complete Markdown guide.

How Mermaid works in Markdown

You write a Mermaid diagram inside a fenced code block labeled mermaid. The editor detects the label and renders the text as a diagram instead of showing it as code:

```mermaid
flowchart LR
    A[Idea] --> B{Draft in Markdown}
    B --> C[Preview]
    C --> D[Export to PDF]
```

That short description renders as a left-to-right flowchart connecting four labeled steps. Change the text and the diagram updates — no drawing tools, no dragging.

Diagram types you can make

Mermaid supports many diagram types from the same plain-text approach. The most useful in everyday writing:

  • Flowcharts — processes and decision trees (flowchart or graph).
  • Sequence diagrams — interactions over time, great for APIs and workflows.
  • Gantt charts — simple project timelines.
  • Class and entity-relationship diagrams — for software and data models.
  • Pie charts and mind maps — quick visual summaries.

Flowchart example

flowchart TD
    Start --> Decision{Is it formatted?}
    Decision -->|Yes| Export[Export to PDF]
    Decision -->|No| Edit[Keep editing]
    Edit --> Decision

Nodes in square brackets [ ] are boxes; braces { } make a decision diamond; --> draws an arrow, and |text| labels it. TD means top-down; LR means left-to-right.

Sequence diagram example

sequenceDiagram
    Writer->>Editor: Type Markdown
    Editor->>Preview: Render live
    Preview-->>Writer: Show result

Here ->> is a message and -->> is a response — a readable way to describe a conversation between participants.

Why diagrams-as-text is powerful

  • Version friendly. A diagram is just text, so it lives in your document, syncs instantly and works with version history — you can see exactly what changed.
  • Fast to edit. Adjust a label or add a step by typing, not by re-arranging shapes.
  • Consistent styling. Every diagram in your document looks uniform automatically.
  • It stays with your writing. No separate image files to manage or keep in sync.

Making diagrams in Inkiostro

On Mac, Inkiostro renders Mermaid diagrams live from your Markdown — write the mermaid code block and the flowchart or sequence diagram appears in the preview as you type. Like LaTeX math, the diagrams are preserved when you export to PDF, HTML or EPUB, so your visuals travel with the document. It turns a plain note into an illustrated one without ever leaving the editor.

Tips

  • Start with flowchart — it’s the most useful type and easy to read.
  • Keep node labels short so the layout stays clean; Mermaid arranges the boxes for you.
  • Choose a direction (TD top-down or LR left-to-right) that suits the flow.
  • Preview often — a small syntax slip is obvious the moment it fails to render.

FAQ

What is Mermaid in Markdown?

Mermaid is a syntax for describing diagrams — flowcharts, sequence diagrams, Gantt charts and more — in plain text. You put it in a fenced code block labeled mermaid, and a supporting editor renders it as a diagram. Inkiostro supports Mermaid natively on Mac.

Does standard Markdown support diagrams?

Not on its own. Diagrams are an extension: editors that support Mermaid recognize a mermaid code block and render its contents. Plain Markdown would just show the code.

How do I make a flowchart in Markdown?

Write a fenced code block labeled mermaid, start it with flowchart LR (or TD), then define nodes and arrows like A --> B. In Inkiostro on Mac the flowchart renders live in the preview.

Can I export Markdown diagrams to PDF?

Yes. In Inkiostro on Mac, Mermaid diagrams render in the preview and are included when you export to PDF, HTML or EPUB.

Do I need drawing skills to make diagrams this way?

No. You describe the diagram in words — the boxes, arrows and layout are generated for you. It’s ideal for people who want clear diagrams without a design tool.