Шпаргалка по синтаксису mermaid

Самая короткая рабочая диаграмма

Flowchart нужна одна строка объявления и одна стрелка. TD значит сверху вниз; для широких процессов лучше подходит LR — слева направо.

flowchart TD
  A[Start] --> B{Ready?}
  B -->|Yes| C[Ship it]
  B -->|No| A

A, B и C — это id узлов, внутренние имена, которые никогда не рисуются. Текст в скобках — подпись, а стиль скобок как раз и определяет форму.

Формы узлов

Форма выбирается парой скобок вокруг подписи. Вот те, что стоит запомнить:

💡Берите подпись в кавычки, если в ней есть скобки, двоеточия или кавычки: A["Load (raw) data"]. Без кавычек парсер примет вашу пунктуацию за синтаксис.

Стрелки

Длина стрелки тоже имеет значение: --> — один уровень, ---> отодвигает цель на уровень дальше. Это самый простой способ управлять раскладкой в mermaid.

Группировка через подграфы

subgraph рисует подписанную рамку вокруг узлов. Подграфы можно вкладывать друг в друга, а стрелки свободно пересекают их границы.

flowchart LR
  subgraph api["API"]
    H[Handler] --> S[(Postgres)]
  end
  subgraph worker["Worker"]
    Q[Queue] --> W[Job]
  end
  H --> Q

Цвет и стили

style красит один узел. classDef вместе с class красит целый набор — это нужно уже после трёх-четырёх узлов.

flowchart TD
  A[OK] --> B[Failed]
  style A fill:#16a34a,stroke:#333,color:#fff
  classDef bad fill:#dc2626,stroke:#333,color:#fff
  class B bad

Цвета — часть исходника диаграммы, поэтому они переживают экспорт и путешествуют вместе с файлом. Ничего здесь не зависит от настройки темы в инструменте, который это рендерит.

По одному примеру на тип диаграммы

Sequence-диаграмма

sequenceDiagram
  participant User
  participant API
  participant DB
  User->>API: request
  API->>DB: query
  DB-->>API: rows
  API-->>User: response

Диаграмма классов

classDiagram
  class Animal {
    +String name
    +move()
  }
  class Dog {
    +bark()
  }
  Animal <|-- Dog

Диаграмма состояний

stateDiagram-v2
  [*] --> Idle
  Idle --> Running: start
  Running --> Idle: stop
  Running --> [*]: finish

Диаграмма «сущность-связь»

erDiagram
  CUSTOMER ||--o{ ORDER : places
  ORDER ||--|{ LINE_ITEM : contains
  CUSTOMER {
    string name
    string email
  }

Диаграмма Ганта

gantt
  title Project
  dateFormat YYYY-MM-DD
  section Phase 1
  Task 1 :a1, 2026-01-01, 5d
  Task 2 :after a1, 5d

Где mermaid рендерится сам по себе

• GitHub — блок в тройных кавычках ```mermaid рендерится в issues, pull request'ах, комментариях и README.
• GitLab — тот же блок, в issues, merge request'ах и вики.
• Notion — блок кода с языком Mermaid рендерится рядом с исходником.
• Obsidian — блок mermaid рендерится в режиме предпросмотра.
• Сайты документации — Docusaurus, MkDocs Material и VitePress поддерживают блоки mermaid.

Вот настоящая причина держать диаграммы как mermaid, а не как картинки: диаграмма живёт в том же текстовом файле, что и то, что она описывает, и код-ревью видит, что в ней изменилось.