1.10 Mermaid

1. What Is Mermaid

Mermaid is a tool that describes charts in text: through keywords such as flowchart and sequenceDiagram, you define flowcharts, sequence diagrams, class structures, and other charts in plain text, and a renderer then generates the corresponding graphics. The chart source is just ordinary text, usually written directly in a Markdown code block.

Precisely because charts are described in text, compared with dragging in drawing software (Visio, draw.io), it has several natural advantages:

• Plain text: it can be written into Markdown and versioned with Git
• Maintainable: updating a chart only requires editing text, not re-taking screenshots
• Searchable: chart content can be found with grep
• Reusable: GitHub, GitLab, and many documentation tools can render common charts

2. Using It in Markdown

Just put Mermaid code in a ```mermaid code block:

```mermaid
flowchart TD
    A[Start] --> B{Decision}
    B -->|Yes| C[Execute Operation]
    B -->|No| D[End]
```

Effect:

Mermaid provides more than twenty chart types; the common ones are listed below:

Beyond the table, there are domain-specific types such as Requirement diagrams, C4 architecture diagrams, ZenUML, Sankey, XY charts, and Kanban, which appear less often in this documentation. The common types are introduced one by one below.

3. Flowchart

The flowchart is the most commonly used chart type, for representing processes, decisions, and steps.

3.1 Direction

3.2 Node Shapes

Different brackets denote different shapes:

3.3 Connecting Lines

3.4 Subgraphs

Use subgraph to group related nodes:

4. Sequence Diagram

A sequence diagram describes the message interactions and their order between multiple objects, suitable for expressing API calls and request-response flows:

4.1 Message Types

4.2 Adding Notes

Use Note over to add an annotation to an interaction:

Class diagrams can be used to describe the members of a type and the relationships between classes in object-oriented design.

5. Class Diagram

Used to describe the class structure, fields, methods, and relationships between classes of objects:

5.1 Relationship Symbols

Mermaid also provides Gantt charts, pie charts, and state diagrams, suitable for expressing plans, proportions, and state transitions respectively.

6. Gantt

Gantt charts suit project planning and scheduling timelines:

7. Pie

Used to show each part's proportion of the whole:

8. State Diagram

Used to describe the state transitions of an object, suitable for expressing protocols, state machines, and so on:

9. Other Chart Types

Besides the high-frequency types introduced above, Mermaid has a few more chart types that are also used often.

9.1 Entity Relationship (ER) Diagram

Describes entities (such as database tables) and the cardinality relationships between them; commonly used in database courses:

The symbols at the two ends of a relationship denote cardinality constraints: || means exactly one, and o{ means zero or more; read together, "one student can enroll in many courses, and one course can be enrolled by many students". Entity attributes are written inside the braces, and PK denotes the primary key.

9.2 Git Graph

Use commits, branches, and merges to visualize repository history; you can read it together with 1.15 Version Control and Git:

9.3 Mindmap

Expand layer by layer from a central topic, suitable for organizing a knowledge system and study notes:

9.4 Timeline

Arranges events in chronological order, suitable for course plans, project milestones, and personal records:

The types above already cover most scenarios in daily study and work; for other domain-specific types, consult the official documentation when you need them. After mastering the common types, a few practical tips will make your charts more professional.

10. Practical Tips

10.1 Separating Node IDs from Text

A node can be defined in the form id[text]; later references only need to write id, without repeating the text:

flowchart TD
    A[Start] --> B[Process]
    B --> A

10.2 Comments

Use %% to write comments, which are not rendered in the chart:

flowchart TD
    %% This is a comment; it will not appear in the chart
    A --> B

10.3 Style Customization

Use classDef to define a style, then apply it to nodes with ::::

flowchart LR
    A:::highlight --> B
    classDef highlight stroke-width:3px

Check specific colors in both light and dark themes; if the publishing platform provides theme variables or site-level styles, reuse them first, so that node text does not lose contrast with the background.

10.4 Avoiding Overly Complex Charts

11. Online Editing and Debugging

12. TODO Checklist

• Can choose the appropriate chart type according to the nature of the information (flow, interaction, structure, state, time, proportion, etc.)
• Can write clear node text and IDs, keeping the structure clear
• Can split and simplify complex charts while keeping the main flow clear
• Can draw charts with AI assistance

13. Questions Worth Thinking About