Skip to main content

Mermaid Syntax Guide

Mermaid Cheat Sheet & Syntax Guide.

A complete Mermaid cheat sheet containing copy-paste syntax examples for flowcharts, sequence diagrams, ERDs, Gantt charts, mindmaps, and timelines. Render diagrams locally in your documentation.

View Diagram Syntax Open Mermaid Viewer

Syntax Pattern

```mermaid
flowchart LR
  A[Write Markdown] --> B[Add Mermaid code]
  B --> C[Preview diagram]
  C --> D[Publish docs]
```

Drop this fenced code block directly into Markdown, then preview it in our client-side editor or a Mermaid-capable parser.

Step 1

Choose Diagram Type

Start with a diagram keyword like flowchart, timeline, or sequenceDiagram.

Step 2

Add Relationships

Use arrows, time splits, and structural definitions to map relationships in readable, plaintext lines.

Step 3

Live Rendering

Render your diagrams instantly to check for syntax issues, layout errors, or overlapping elements before publishing.

Flowcharts Sequence Timeline ER Diagrams Class State Gantt Pie Charts Mindmaps Mistakes

mermaid flowchart syntax

Mermaid Flowchart Syntax

Flowcharts are the best place to start with Mermaid. Use them for decisions, pipelines, workflows, and process mapping that moves from one step to another.

Copyable Syntax

Flowcharts

flowchart TD
  A[Draft Markdown] --> B{Needs a diagram?}
  B -- Yes --> C[Write Mermaid code]
  B -- No --> D[Publish notes]
  C --> E[Preview and export]
  E --> D

Rendered Preview

Processes, branches, decisions, workflows

Rendering Mermaid Preview

The syntax remains visible if JavaScript is disabled.

Start with flowchart, then choose TD for top-down or LR for left-to-right.

Use square brackets for process nodes and curly braces for decisions.

Label lines with text between dashes, such as -- Yes -->.

mermaid sequence diagram syntax

Mermaid Sequence Diagram Syntax

Sequence diagrams display messages over time. They are ideal for detailing API calls, authentication steps, browser interactions, and service communication.

Copyable Syntax

Sequence

sequenceDiagram
  participant User
  participant App
  participant Renderer
  User->>App: Paste Mermaid syntax
  App->>Renderer: Validate diagram
  Renderer-->>App: SVG preview
  App-->>User: Export options

Rendered Preview

APIs, request-response flows, service messages

Rendering Mermaid Preview

The syntax remains visible if JavaScript is disabled.

Declare participants to control order and display names.

Use ->> for request calls and -->> for response returns.

Write the message label after a colon.

mermaid diagram timeline example

Mermaid Timeline Diagram Syntax

Timeline diagrams show events in chronological order. They are perfect for release history, roadmap milestones, project schedules, and historical records.

Copyable Syntax

Timeline

timeline
  title History of Markdown
  2004 : Markdown Created : John Gruber & Aaron Swartz
  2011 : CommonMark Standard Launched
  2014 : GitHub Flavored Markdown (GFM)
  2026 : TheMarkdowner Browser Tools

Rendered Preview

Release logs, roadmaps, project history, schedules

Rendering Mermaid Preview

The syntax remains visible if JavaScript is disabled.

Start with the timeline keyword.

Define periods followed by a colon, then specify individual events.

Use colons to separate multiple events under the same time block.

mermaid er diagram syntax

Mermaid ER Diagram Syntax

Entity relationship diagrams map database tables and their relationships. Use them to document schema structures, content models, and API data contracts.

Copyable Syntax

ER Diagrams

erDiagram
  DOCUMENT ||--o{ DIAGRAM : contains
  DOCUMENT {
    string title
    string format
  }
  DIAGRAM {
    string type
    string source
  }

Rendered Preview

Database schemas, relationship models, data structure

Rendering Mermaid Preview

The syntax remains visible if JavaScript is disabled.

Declare erDiagram on the first line.

Define connections using relationship symbols like ||--o{ (one-to-many).

Wrap table properties inside curly braces.

mermaid class diagram syntax

Mermaid Class Diagram Syntax

Class diagrams display objects, properties, methods, and relationships. They are highly useful for software SDK specs and object-oriented designs.

Copyable Syntax

Class

classDiagram
  class Document {
    +string title
    +string format
    +convertToMarkdown()
  }
  class Diagram {
    +string type
    +render()
  }
  Document "1" --> "0..*" Diagram : includes

Rendered Preview

Objects, properties, classes, code structure

Rendering Mermaid Preview

The syntax remains visible if JavaScript is disabled.

Start with classDiagram at the top.

Use + for public fields or methods, and - for private ones.

Specify relationship associations with lines like -->.

mermaid state diagram syntax

Mermaid State Diagram Syntax

State diagrams map dynamic modes and transition rules. Perfect for order lifecycles, user state updates, and editor view modes.

Copyable Syntax

State

stateDiagram-v2
  [*] --> Draft
  Draft --> Preview: render
  Preview --> Error: syntax issue
  Preview --> Published: export
  Error --> Draft: fix code

Rendered Preview

Lifecycles, modes, transitions, operations

Rendering Mermaid Preview

The syntax remains visible if JavaScript is disabled.

Use stateDiagram-v2 for the modern state rendering syntax.

Represent the start and end of a flow using [*].

Add action or event labels after a colon.

mermaid gantt chart syntax

Mermaid Gantt Chart Syntax

Gantt charts display tasks against project timelines. Excellent for mapping out content sprints, milestones, and release plans.

Copyable Syntax

Gantt

gantt
  title Documentation Release
  dateFormat  YYYY-MM-DD
  section Draft
  Write guide      :a1, 2026-06-12, 2d
  Review examples  :after a1, 1d
  section Publish
  Add screenshots  :1d
  Launch page      :1d

Rendered Preview

Timeline schedules, milestones, sprint tracks

Rendering Mermaid Preview

The syntax remains visible if JavaScript is disabled.

Declare dateFormat to match task formats (e.g. YYYY-MM-DD).

Organize items in sections using the section keyword.

Sequence tasks using after task-id to chain dependencies.

mermaid pie chart syntax

Mermaid Pie Chart Syntax

Pie charts display distribution percentages. Use them to show split proportions, traffic distributions, or content weight summaries.

Copyable Syntax

Pie Charts

pie showData
  title Diagram Types in a Docs Page
  "Flowcharts" : 40
  "Sequence diagrams" : 25
  "ER diagrams" : 20
  "Other" : 15

Rendered Preview

Distribution splits, shares, statistics

Rendering Mermaid Preview

The syntax remains visible if JavaScript is disabled.

Use pie showData to render raw numbers beside labels.

Enclose names with double quotes if they contain spaces.

Keep segment numbers short and simple.

mermaid mindmap syntax

Mermaid Mindmap Syntax

Mindmaps display structured hierarchies and brain outlines. Organize features, taxonomies, and topics with indentation.

Copyable Syntax

Mindmaps

mindmap
  root((Mermaid))
    Markdown
      README files
      Docs sites
    Diagrams
      Flowcharts
      Sequence
      ERD

Rendered Preview

Outline structures, brainstorm charts, hierarchies

Rendering Mermaid Preview

The syntax remains visible if JavaScript is disabled.

Use indentation spacing to nest child branches.

Declare root((Node)) for a distinct visual core.

Keep nodes short to preserve diagram spacing.

Troubleshooting

Common Mermaid Syntax Mistakes

Most Mermaid errors stem from a missing diagram type identifier, a mismatched arrow symbol, or a label that requires double quotes. If a diagram fails to compile, simplify the code to a single relationship, then incrementally add lines back.

Missing Diagram Identifier

Mermaid blocks require a starting keyword line (e.g. flowchart, sequenceDiagram, erDiagram) so the parser knows what structure to build.

Incorrect Arrow Punctuation

Arrows are specific to diagram types. Flowcharts use -->, whereas sequence diagrams require ->> and returns with -->>.

Special Character Crashes

Special symbols inside node names can crash the parser. Wrap labels in double quotes or define node IDs separately from display names.

Broken Indentation

Mindmaps and timeline roadmaps rely heavily on indentation spacing. Ensure nested child elements have identical indentation patterns.

Next Step

Preview Mermaid Diagrams From Markdown

Paste a full Markdown file, detect every fenced Mermaid block, and export diagrams as SVG, PNG, or PDF without uploading your docs.

Open Viewer

Mermaid In Markdown

Why Mermaid Syntax Works Well For Documentation

Mermaid is a popular diagramming utility because the code representation lives alongside the markdown prose it explains. Instead of managing binary images via separate editors, you declare flowcharts, ERDs, sequence structures, and timeline logs as plaintext in the same markdown file. This keeps system design diagrams in version control, makes design reviews simple via Git diffs, and keeps architecture documentation fully aligned with the codebase.

For search engine optimization and user discoverability, this Mermaid cheat sheet operates alongside our Markdown guide. Developers looking for Mermaid documentation are usually seeking concrete syntax formulas: how to write a flowchart in markdown, how to render sequence diagrams, or how to map an entity database schema. Placing these copyable examples on a dedicated "Mermaid Cheat Sheet" page answers that user intent directly, driving high organic search traffic to the site.

The examples highlighted in this syntax guide cover the most common needs in software engineering documentation. Flowcharts describe operations and logic blocks. Sequence diagrams map chronological service interactions. ER diagrams detail data schemas. State diagrams describe states and mode variations. Gantt charts map out project releases, while timelines map milestones and history segments.

Combined with TheMarkdowner's capability to extract Markdown structures from PDF, DOCX, HTML, and CSV data, this Mermaid reference provides a cohesive solution for writing, editing, and previewing docs. Author your syntax, check the output in our browser-based visualizer, and export clean graphics without uploading files to third-party servers.

Mermaid Cheat Sheet FAQ

How do I use Mermaid inside Markdown files?

Simply wrap your diagram syntax inside a fenced code block with the mermaid identifier, like ```mermaid. Many markdown editors, platforms (like GitHub and GitLab), and static site engines will detect and render it automatically.

How is this Mermaid Cheat Sheet structured?

This sheet lists common diagram syntax patterns (flowcharts, sequence diagrams, timelines, and entity relationship models) alongside copy-paste code blocks and live SVG previews. Use it as a reference for writing diagrams.

Can I export Mermaid diagrams to image formats?

Yes. Copy your diagram code and paste it into our free online Mermaid Markdown Viewer to preview it instantly and download the output as clean SVG, PNG, or PDF formats.

What is a Mermaid diagram and what does it do?

A Mermaid diagram is a chart or visual diagram generated using Mermaid.js, a JavaScript charting tool. It uses simple, text-based code syntax inspired by Markdown to render flowcharts, sequence diagrams, state machines, class diagrams, Gantt charts, and user journeys dynamically.

How do you open, view, or render a Mermaid diagram?

You can view and render Mermaid diagrams using TheMarkdowner's Mermaid Diagram Viewer. Paste your Markdown document containing Mermaid code blocks or write the raw Mermaid definitions directly. The viewer parses the diagram instructions and outputs a high-resolution SVG diagram that you can edit, zoom, and download.

How do you render a Mermaid diagram in Markdown?

To render a Mermaid diagram in Markdown, wrap the chart definitions inside a fenced code block marked with the language mermaid. For example:

```mermaid
graph TD;
    Start --> Process;
    Process --> End;
```

Many modern platforms like GitHub, GitLab, Obsidian, and VS Code extensions will automatically compile and render this into a visual graph.

How do you add a Mermaid diagram in Confluence?

To add a Mermaid diagram in Atlassian Confluence, edit a page, type /mermaid to search and insert the Mermaid macro (requires the Mermaid plugin for Confluence to be installed), and paste your diagram code. If your space doesn't support the plugin, export your diagram as an SVG or PNG from TheMarkdowner's Mermaid Viewer and upload it as a static image.

How do you make a diagram using Mermaid code?

You build diagrams using simple syntax declaration: state the diagram direction (e.g. graph TD for Top-Down or graph LR for Left-to-Right), declare node IDs, and draw relationships with connections like --> or ---. For example, graph TD; A --> B makes node A point to node B. You can paste and test this code in TheMarkdowner's Mermaid Viewer.