Diagram Syntax Reference

Mermaid Cheat Sheet & Syntax Guide

Copy a working example for the diagram you need, see how it renders, and adapt the labels and relationships for your documentation.

View Diagram Syntax Mermaid Viewer

Syntax Pattern

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

Fenced code blocks with the mermaid identifier render into interactive diagrams automatically.

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

mermaid flowchart syntax

Mermaid flowchart syntax

Use a flowchart to show how a process moves from one step to the next, including decisions and alternate paths.

Copyable Syntax

Flowcharts

Try in Editor

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 show messages in time order. They work well for API calls, authentication, browser interactions, and communication between services.

Copyable Syntax

Sequence

Try in Editor

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 syntax

Timelines arrange events in chronological order. Use them for release history, roadmap milestones, and other dated records.

Copyable Syntax

Timeline

Customize

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.

More timeline patterns

4 Mermaid timeline examples to copy

Open in generator

Basic timeline with a title

A minimal chronological history with one event per period.

timeline
  title Product History
  2024 : First prototype
  2025 : Private beta
  2026 : Public launch

Customize

Multiple events in one period

Use additional colons to place related milestones under one time period.

timeline
  title 2026 Release Plan
  Q1 : Customer research : Roadmap approved
  Q2 : Private beta : Documentation
  Q3 : General availability : Adoption review

Customize

Sprint roadmap

Group delivery periods with sections for a readable software roadmap.

timeline
  title Software Sprints
  section Discovery
  Sprint 1 : Define scope : Prototype
  section Delivery
  Sprint 2 : Build editor : Add validation
  section Release
  Sprint 3 : Accessibility review : Launch

Customize

Release history

Document software versions and notable changes in chronological order.

timeline
  title Release History
  v1.0 : Initial release : Core editor
  v1.1 : SVG export : Dark theme
  v2.0 : Timeline builder : Shareable links

Customize

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 show database entities and the connections between them. Use one to document a schema, content model, or data contract.

Copyable Syntax

ER Diagrams

Try in Editor

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 show objects, properties, methods, and relationships. They are useful for SDK documentation and object-oriented designs.

Copyable Syntax

Class

Try in Editor

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 show the valid states of a system and the events that move it between them. Use one for an order lifecycle, user status, or interface mode.

Copyable Syntax

State

Try in Editor

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 place tasks on a dated schedule. Use one when a plan needs start dates, durations, milestones, or dependencies.

Copyable Syntax

Gantt

Try in Editor

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 show how a small set of categories contributes to one total. Use them for proportions such as traffic sources or survey responses.

Copyable Syntax

Pie Charts

Try in Editor

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 mind map syntax

Mind maps organize a central topic and its branches. Mermaid uses indentation to build the hierarchy.

Copyable Syntax

Mindmaps

Try in Editor

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.

Syntax Utilities

Mermaid comments and special characters

Comments and escaped labels work across diagram types, so they belong outside the timeline syntax itself. Use comments for maintainer notes and HTML entities when a label contains syntax punctuation.

Add a Mermaid comment

Lines beginning with %% stay in the source but do not render.

timeline
  %% Internal launch plan
  title Product Roadmap
  Q3 2026 : Public release

Escape syntax punctuation

Use an HTML entity when a colon belongs inside a label.

timeline
  title Product Roadmap
  Q3 2026 : Launch at 10&#58;00 UTC

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 -->>.

Unquoted special characters

Punctuation inside a label can be mistaken for Mermaid syntax. Wrap the label in double quotes or keep the node ID separate from its display text.

Broken indentation

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

Frequently Asked Questions

How is this Mermaid Cheat Sheet structured?

Each section pairs a working code block with a rendered preview and syntax notes. Start with the diagram type you need, copy the example, and replace its labels.

Can I export Mermaid diagrams to image formats?

Yes. Paste the code into the Mermaid editor, check the live preview, and download SVG, PNG, or PDF.

Are Mermaid diagrams supported on GitHub?

Yes. GitHub, GitLab, and Obsidian natively render fenced ```mermaid code blocks in Markdown files and issues.