Mermaid Syntax Basics: A Classroom-Friendly Tutorial

1. What Mermaid Does

Mermaid turns plain text into diagrams. Instead of dragging boxes around, you describe the structure. This makes diagrams easy to revise, copy, store, and generate with AI.

Simple

Write text

Use short lines such as A[Start] --> B[Next Step]. Each line adds a shape, connection, or label.

Visual

Render diagrams

Paste Mermaid code into a Mermaid-compatible editor, note app, documentation tool, or this webpage.

Editable

Revise quickly

Change words or connections in the code, then re-render. The diagram updates without redrawing from scratch.

Best beginner habit: Build one diagram in three passes: first the diagram type, then the main boxes, then the labels and styling.

2. A Better Prompt Formula

When asking AI to create Mermaid diagrams, describe the diagram like a teacher giving clear board directions.

Use this four-part prompt

Diagram type: flowchart, sequence diagram, timeline, Gantt chart, ER diagram, etc.
Topic: the classroom concept, process, project, or relationship.
Required parts: exact labels, steps, or categories.
Connections: arrows, direction, labels, loops, decisions, or groups.

Copy-ready AI prompt

Create a Mermaid [diagram type] about [topic].
Use these exact labels: [list labels].
Show these relationships: [describe arrows or sequence].
Keep labels short and classroom-friendly.
Return only valid Mermaid code in one code block.

Important: Ask for valid Mermaid code. AI tools sometimes use smart quotes, long dashes, or malformed arrows. Replace curly quotes with straight quotes and use Mermaid arrows such as -->, --->, -->|Label|, or <-->.

3. Core Examples

Each example includes a classroom use case, clean Mermaid code, and a rendered diagram. Use the copy buttons to reuse the code.

Example A: Flowchart — Photosynthesis Inputs and Outputs

A flowchart is best when students need to explain steps, inputs, outputs, or cause-and-effect.

Mermaid code

flowchart TD
    Sun[Sunlight] --> Process[Photosynthesis]
    CO2[Carbon Dioxide] --> Process
    Water[Water] --> Process
    Process --> Sugar[Glucose]
    Process --> Oxygen[Oxygen]

Rendered diagram

flowchart TD
    Sun[Sunlight] --> Process[Photosynthesis]
    CO2[Carbon Dioxide] --> Process
    Water[Water] --> Process
    Process --> Sugar[Glucose]
    Process --> Oxygen[Oxygen]

Example B: Decision Flowchart — Choose a Research Source

Decision diagrams help students make choices using evidence and conditions.

Mermaid code

flowchart TD
    A[Find a source] --> B{Is the author credible?}
    B -- Yes --> C{Is it current enough?}
    B -- No --> F[Find another source]
    C -- Yes --> D[Use the source]
    C -- No --> E[Check for newer evidence]
    E --> F

Rendered diagram

flowchart TD
    A[Find a source] --> B{Is the author credible?}
    B -- Yes --> C{Is it current enough?}
    B -- No --> F[Find another source]
    C -- Yes --> D[Use the source]
    C -- No --> E[Check for newer evidence]
    E --> F

Example C: Sequence Diagram — Student Feedback Loop

Sequence diagrams show who talks to whom, in what order. They work well for workflows, protocols, and feedback cycles.

Mermaid code

sequenceDiagram
    participant Student
    participant AI as AI Tutor
    participant Teacher
    Student->>AI: Draft explanation
    AI-->>Student: Ask clarifying question
    Student->>Teacher: Submit revised draft
    Teacher-->>Student: Give targeted feedback

Rendered diagram

sequenceDiagram
    participant Student
    participant AI as AI Tutor
    participant Teacher
    Student->>AI: Draft explanation
    AI-->>Student: Ask clarifying question
    Student->>Teacher: Submit revised draft
    Teacher-->>Student: Give targeted feedback

Example D: State Diagram — States of Matter

State diagrams show how something changes from one condition to another.

Mermaid code

stateDiagram-v2
    [*] --> Solid
    Solid --> Liquid: Melting
    Liquid --> Solid: Freezing
    Liquid --> Gas: Vaporization
    Gas --> Liquid: Condensation
    Solid --> Gas: Sublimation
    Gas --> Solid: Deposition

Rendered diagram

stateDiagram-v2
    [*] --> Solid
    Solid --> Liquid: Melting
    Liquid --> Solid: Freezing
    Liquid --> Gas: Vaporization
    Gas --> Liquid: Condensation
    Solid --> Gas: Sublimation
    Gas --> Solid: Deposition

Example E: Timeline — Civil Rights Movement Milestones

Timelines work well for historical events, project stages, book chapters, or scientific discoveries.

Mermaid code

timeline
    title Civil Rights Movement Milestones
    1954 : Brown v. Board of Education
    1955 : Montgomery Bus Boycott
    1963 : March on Washington
    1964 : Civil Rights Act
    1965 : Voting Rights Act

Rendered diagram

timeline
    title Civil Rights Movement Milestones
    1954 : Brown v. Board of Education
    1955 : Montgomery Bus Boycott
    1963 : March on Washington
    1964 : Civil Rights Act
    1965 : Voting Rights Act

Example F: Gantt Chart — Science Fair Project

Gantt charts are useful for project planning because they show tasks, dependencies, and timing.

Mermaid code

gantt
    title Science Fair Project Timeline
    dateFormat  YYYY-MM-DD
    axisFormat  %b %d
    section Plan
    Choose topic      :a1, 2026-09-01, 5d
    Research question :a2, after a1, 5d
    section Build
    Run experiment    :a3, after a2, 10d
    Analyze data      :a4, after a3, 5d
    section Share
    Create poster     :a5, after a4, 5d
    Present findings  :milestone, after a5, 1d

Rendered diagram

gantt
    title Science Fair Project Timeline
    dateFormat  YYYY-MM-DD
    axisFormat  %b %d
    section Plan
    Choose topic      :a1, 2026-09-01, 5d
    Research question :a2, after a1, 5d
    section Build
    Run experiment    :a3, after a2, 10d
    Analyze data      :a4, after a3, 5d
    section Share
    Create poster     :a5, after a4, 5d
    Present findings  :milestone, after a5, 1d

Example G: Entity Relationship Diagram — School Courses

ER diagrams show relationships between entities. They are useful for database design, information systems, and organizing complex records.

Mermaid code

erDiagram
    STUDENT ||--o{ ENROLLMENT : has
    COURSE ||--o{ ENROLLMENT : includes
    TEACHER ||--o{ COURSE : teaches

    STUDENT {
      int student_id
      string name
      string grade_level
    }
    COURSE {
      int course_id
      string course_name
    }
    TEACHER {
      int teacher_id
      string name
      string department
    }

Rendered diagram

erDiagram
    STUDENT ||--o{ ENROLLMENT : has
    COURSE ||--o{ ENROLLMENT : includes
    TEACHER ||--o{ COURSE : teaches

    STUDENT {
      int student_id
      string name
      string grade_level
    }
    COURSE {
      int course_id
      string course_name
    }
    TEACHER {
      int teacher_id
      string name
      string department
    }

Example H: Pie Chart — Favorite Science Topics

Pie charts work for quick category comparisons. Keep them simple and use clear labels.

Mermaid code

pie showData
    title Favorite Science Topics
    "Biology" : 43
    "Chemistry" : 30
    "Physics" : 27

Rendered diagram

pie showData
    title Favorite Science Topics
    "Biology" : 43
    "Chemistry" : 30
    "Physics" : 27

4. Try Mermaid Here

Edit the code, then render it. This is useful for checking whether a diagram is valid before pasting it into a blog, LMS, document, or slide deck.

Ready

5. Troubleshooting Mermaid Code

Most Mermaid errors come from punctuation, spacing, unsupported characters, or mixed diagram types.

Problem	Likely cause	Fix
Diagram does not render	Wrong diagram starter or malformed line	Start with a valid type: `flowchart TD`, `sequenceDiagram`, `stateDiagram-v2`, `erDiagram`, `timeline`, or `gantt`.
Arrows look broken	Smart punctuation from a word processor or AI response	Use plain arrows: `-->`, `--`, `-->\|Label\|`, `<-->`.
Label text causes errors	Special characters inside labels	Keep labels short. For tricky text, wrap labels in quotes or simplify punctuation.
Gantt chart dates fail	Date does not match `dateFormat`	If using `dateFormat YYYY-MM-DD`, every date should look like `2026-09-01`.
AI output includes Markdown fences	The code includes ```mermaid lines	Remove the opening and closing code fence before rendering in this page.

6. Quick Reference Card

Print this section or copy the snippets into your notes. These are the most useful patterns for beginners.

Mermaid Quick Reference

Flowchart startersflowchart TD top-down
flowchart LR left-to-right

Basic arrowA[Start] --> B[Next]

Labeled arrowA -->|Feedback| B

Decision diamondA{Question?}

Rounded start/endA([Start])

Database shapeA[(Data)]

Subgraph

subgraph Group
  A --> B
end

Sequence messageStudent->>Teacher: Question

State transitionSolid --> Liquid: Melting

Timeline entry2026 : Event label

Pie entry"Category" : 25

Gantt taskResearch :a1, 2026-09-01, 7d

Common diagram starters

flowchart TD
sequenceDiagram
stateDiagram-v2
erDiagram
gantt
timeline
pie showData
mindmap

Reliable AI prompt starter

Create valid Mermaid code for a [diagram type] about [topic].
Use short labels for K-12 educators and students.
Return only the Mermaid code. Do not include explanations.

7. Classroom Uses

Mermaid is most useful when students need to make thinking visible, not when they need a polished poster.

Science

Model cycles, lab procedures, food webs, systems, variables, and cause-effect chains.

Social Studies

Build timelines, decision trees, power structures, treaty relationships, and cause-effect maps.

ELA

Map plot structure, character relationships, argument claims, evidence trails, and revision workflows.

Math

Show problem-solving steps, function-machine logic, proof structure, and multi-step reasoning.

CTE / Computer Science

Document workflows, app logic, database relationships, systems, and user interactions.

Teacher Planning

Create lesson flows, intervention pathways, project timelines, PLC workflows, and curriculum maps.

Student task idea: Give students a finished diagram and ask them to write the Mermaid code that would recreate it. Then reverse the task: give them Mermaid code and ask them to explain the diagram in plain language.