Синтаксис Mermaid: примеры диаграмм и шпаргалка

Что такое Mermaid и где он работает#

Mermaid — это язык описания диаграмм обычным текстом и библиотека, которая рисует по этому тексту картинку. Вы не двигаете прямоугольники мышью, а пишете A --> B, и на экране появляются два блока со стрелкой. Подход называют «диаграммы как код»: схема хранится рядом с исходниками, правится в любом редакторе и проходит ревью вместе с кодом.

Главная причина популярности Mermaid — поддержка в местах, где программисты и так пишут тексты. GitHub и GitLab показывают диаграмму прямо в Markdown: достаточно поместить текст в блок кода с пометкой mermaid. Многие вики, редакторы заметок и генераторы документации тоже умеют его рисовать — сами или с расширением. Для черновиков есть онлайн-редактор Mermaid Live: слева текст, справа картинка, которая обновляется при каждом нажатии клавиши.

• Схема живёт в репозитории. Изменили архитектуру — поправили три строки в том же запросе на слияние, и история изменений схемы видна в истории файла.
• Не нужна отдельная программа. Текст открывается где угодно, а картинку нарисует сервис, в котором его читают.
• Удобно сравнивать версии. Разница между двумя версиями схемы — это разница между двумя текстами, её видно построчно.
• Схему легко сгенерировать. Скрипт, база знаний или нейросеть выдают текст Mermaid, а не картинку, которую потом не исправить.

У подхода есть и обратная сторона: раскладку блоков выбирает библиотека, а не вы. Для схемы из десяти блоков это плюс, для схемы из сотни — частая причина запутанных стрелок. Поэтому Mermaid хорош для небольших схем рядом с кодом, а большие обзорные схемы удобнее собирать на доске. Как понять, нужна ли вообще блок-схема и чем она отличается от других схем процессов, — в статье что такое блок-схема.

Блок-схема: синтаксис flowchart#

Блок-схема — самый ходовой вид диаграмм Mermaid: процессы, алгоритмы, пути пользователя, наброски архитектуры. Разберём её синтаксис по частям: заголовок, блоки, формы, стрелки, группы, комментарии и оформление. Под каждым примером — что сделает с ним NodePanel, если вставить текст на доску: эти подписи проверяются настоящим разборщиком приложения.

flowchart TD
  start([Заявка пришла]) --> check{Всё заполнено?}
  check -->|Да| work[Взять в работу]
  check -->|Нет| back[Вернуть автору]
  work --> done([Готово])

flowchart LR
  idea[Идея] --> proto[Прототип] --> test[Проверка] --> release[Релиз]

flowchart LR
  a[Прямоугольник] --> b(Скруглённый)
  b --> c([Капсула])
  c --> d{Ромб}
  d --> e((Круг))
  e --> f[[Подпрограмма]]
  f --> g[(База данных)]

flowchart LR
  order[Заказ] --> pay[Оплата]
  pay -->|успех| receipt[Чек]
  pay -.->|ошибка| retry[Повтор]
  receipt ==> ship[Доставка]
  ship --- review[Отзыв]
  retry -- через минуту --> pay

flowchart LR
  design[Дизайн] & backend[Бэкенд] & docs[Тексты] --> release[Релиз]

flowchart TB
  subgraph web [Сайт]
    page[Страница] --> form[Форма заказа]
  end
  subgraph server [Сервер]
    api[API] --> db[База]
  end
  form -->|HTTPS| api

flowchart LR
  %% Классы задают цвета в Mermaid
  classDef risk fill:#fde68a,stroke:#b45309
  plan[План] --> risk1[Сжатые сроки]:::risk
  risk1 --> fix[Резерв времени]

Другие виды диаграмм Mermaid#

Кроме блок-схем Mermaid умеет ещё два десятка видов диаграмм. Ниже — семь самых используемых, по короткому рабочему примеру на каждую. Их показывают GitHub, GitLab и другие сервисы с поддержкой Mermaid.

sequenceDiagram
  participant U as Пользователь
  participant S as Сайт
  participant A as API
  U->>S: Нажимает «Оплатить»
  S->>A: POST /payments
  A-->>S: 201 Created
  S-->>U: Страница «Спасибо»

classDiagram
  class Order {
    +id: string
    +total: number
    +pay()
  }
  class Customer {
    +name: string
  }
  Customer "1" --> "*" Order : оформляет

stateDiagram-v2
  [*] --> Черновик
  Черновик --> НаПроверке: отправить
  НаПроверке --> Опубликовано: одобрить
  НаПроверке --> Черновик: вернуть
  Опубликовано --> [*]

erDiagram
  CUSTOMER ||--o{ ORDER : places
  ORDER ||--|{ ORDER_ITEM : contains
  PRODUCT ||--o{ ORDER_ITEM : "is in"

gantt
  title План релиза
  dateFormat YYYY-MM-DD
  section Разработка
  Бэкенд      :a1, 2026-11-02, 10d
  Интерфейс   :a2, after a1, 7d
  section Выпуск
  Тесты       :after a2, 4d

pie title Откуда приходят заявки
  "Поиск" : 46
  "Рекомендации" : 31
  "Соцсети" : 23

mindmap
  root((Запуск продукта))
    Аудитория
      Малый бизнес
      Фрилансеры
    Каналы
      Поиск
      Партнёры
    Риски

Шпаргалка: блок-схема на одном экране#

Mermaid и доска: текст туда и обратно#

Текст и доска хорошо дополняют друг друга. Набросать схему текстом быстро, особенно если её подсказала нейросеть или она уже лежит в README. Обсуждать, двигать и дополнять удобнее на доске. В NodePanel блок-схему Mermaid можно вставить на доску — она станет обычными фигурами, связями и группами, разложенными по направлению из текста, — а готовую доску скопировать обратно текстом flowchart.

1. 1

   Скопируйте текст блок-схемы

   Из README, вики, ответа нейросети или из примеров выше — первая строка должна начинаться с flowchart или graph.

2. 2

   Вставьте на доску

   Нажмите Ctrl+V на холсте или выберите в меню доски «Вставить Mermaid…». Окно покажет, сколько будет блоков и связей, и замечания по строкам.

3. 3

   Доработайте схему

   После вставки это обычная доска: перекрасьте блоки, добавьте стикеры с вопросами, пригласите коллег. Одна отмена убирает всю вставку.

4. 4

   Верните схему в текст

   Меню доски → «Скопировать как Mermaid» — и текст готов для README или документации.

Подробный урок с упражнениями — в руководстве «Схема из текста: Mermaid с нуля»: там по шагам разобрано окно вставки, рецепты и частые ошибки. Попробовать без регистрации можно в песочнице на главной: вставка Mermaid работает и там. Для процесса с нуля подойдёт шаблон блок-схемы процесса, а что ещё умеет доска для процессов — на странице блок-схема онлайн.

Частые ошибки в синтаксисе#

• Стрелка из одного дефиса. -> Mermaid не поймёт — нужно два дефиса: -->.
• Пробел в имени блока. Мой блок --> Конец разберётся не так, как задумано. Имя — одним словом, текст — в надпись: my[Мой блок].
• Незакрытая скобка или кавычка. Одна потерянная скобка ломает строку целиком. Проверяйте пары, особенно в длинных надписях.
• Скобки внутри надписи без кавычек. Надпись со скобками, двоеточием или точкой с запятой берите в кавычки.
• Забытый ``end`` у группы. Тогда в группу попадает всё, что написано ниже, и схема съезжает.
• Слово ``end`` как имя блока. Mermaid примет его за конец группы. Назовите блок finish или done.
• Нет первой строки. Без flowchart или graph текст не считается блок-схемой вовсе.
• Всё в одной схеме. Пятьдесят блоков с перекрёстными стрелками Mermaid нарисует, но читать это никто не станет. Разбейте схему на несколько — по одному вопросу на каждую.

Тот же принцип «одна схема — один вопрос» работает и для архитектурных схем: о том, как разделить систему на уровни детализации, — в статье как нарисовать архитектуру приложения.

Чек-лист перед публикацией схемы#

• Первая строка — flowchart или graph с направлением, которое подходит схеме.
• У каждого блока понятное короткое имя, надпись написана один раз.
• Формы несут смысл: капсула — начало и конец, ромб — вопрос, прямоугольник — действие.
• У каждого ромба подписаны все ветки, ни одна не обрывается в пустоту.
• Пунктир и толстые линии означают то, что написано в легенде.
• Группы закрыты словом end, ни один блок не называется end.
• Надписи со скобками и знаками препинания — в кавычках.
• Схема проверена в просмотре: в редакторе Mermaid, на GitHub или в окне вставки NodePanel.