Диаграммы Mermaid в Markdown: блок-схемы, диаграммы последовательности и не только

Диаграммы объясняют процессы, архитектуру и сроки лучше, чем абзацы текста. Но если рисовать их в графическом редакторе, придётся экспортировать картинки, хранить их рядом с документацией и перерисовывать всё при каждом изменении.

Mermaid решает эту проблему: вы описываете диаграмму несколькими строками текста прямо в Markdown-файле, а программа предпросмотра её рисует. Диаграмма живёт в том же файле, видна в диффах и обновляется так же легко, как предложение. GitHub, GitLab, Obsidian, многие генераторы документации и Markdown Preview Editor отображают Mermaid без дополнительной настройки.

Как добавить диаграмму Mermaid

Создайте блок кода и укажите язык mermaid:

markdown```mermaid
flowchart LR
  A[Пишем] --> B[Смотрим]
  B --> C{Готово?}
  C -- да --> D[Экспорт]
  C -- нет --> A
```

Программа предпросмотра превращает это в:

Первая строка задаёт тип диаграммы. Всё, что ниже, описывает узлы и связи.

Блок-схемы

Блок-схемы — самый популярный тип диаграмм. Направление указывается после ключевого слова: TD или TB (сверху вниз), BT, LR (слева направо) или RL.

mermaidflowchart TD
  start([Начало]) --> input[/Прочитать файл/]
  input --> valid{Файл корректен?}
  valid -- Да --> save[(Сохранить в базу)]
  valid -- Нет --> error[Показать ошибку]
  error --> input

Скобки вокруг подписи задают форму узла:

Связи: --> — стрелка, --- — линия без стрелки, -.-> — пунктирная стрелка, ==> — жирная. Подпись добавляется так: -- text --> или -->|text|.

Связанные узлы можно сгруппировать с помощью subgraph:

mermaidflowchart LR
  subgraph Browser
    editor[Редактор] --> preview[Предпросмотр]
  end
  preview --> export[HTML / PDF]

Диаграммы последовательности

Диаграммы последовательности показывают, как участники обмениваются сообщениями во времени, — идеально для API, процессов аутентификации и пользовательских сценариев.

mermaidsequenceDiagram
  participant U as Пользователь
  participant A as Приложение
  participant S as Сервер
  U->>A: Нажимает «Войти»
  A->>S: POST /login
  S-->>A: 200 OK + токен
  A-->>U: Показывает панель
  Note over A,S: Токен истекает через 1 час

->> — сплошная стрелка (запрос), -->> — пунктирная (ответ). Note over, Note left of и Note right of добавляют комментарии. Блоки loop, alt/else и opt показывают повторения и ветвления.

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

Диаграмма Ганта превращает список задач во временную шкалу. Задача может начинаться в определённую дату или после другой задачи (after).

mermaidgantt
  title Спринт по документации
  dateFormat YYYY-MM-DD
  section Написание
  План          :done,   a1, 2026-10-01, 2d
  Черновик      :active, a2, after a1, 4d
  section Проверка
  Рецензия      :        a3, after a2, 3d
  Публикация    :milestone, after a3, 0d

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

Диаграммы состояний описывают, как что-либо переходит из одного состояния в другое, — заказ, документ, компонент интерфейса.

mermaidstateDiagram-v2
  [*] --> Draft
  Draft --> Review : отправить
  Review --> Draft : нужны правки
  Review --> Published : одобрить
  Published --> [*]

Круговые диаграммы

Чтобы быстро показать доли от целого, круговой диаграмме нужна одна строка на сектор:

mermaidpie title На что уходит время на документацию
  "Написание" : 45
  "Форматирование" : 15
  "Актуализация диаграмм" : 40

Mermaid также поддерживает диаграммы классов, ER-диаграммы, майнд-карты, таймлайны, Git-графы, квадрантные диаграммы и многое другое. Синтаксис каждой описан на официальном сайте Mermaid.

Советы для понятных диаграмм

• Делайте диаграммы небольшими. Схему больше чем на 15–20 узлов трудно читать. Разбейте её на несколько — по одной на идею.
• Выбирайте направление осознанно. LR подходит для процессов из нескольких шагов, TD — для иерархий и длинных цепочек, особенно на узких экранах.
• Используйте короткие ID и понятные подписи. Пишите auth[Проверить сессию], а не используйте подпись как ID, — так связи остаются короткими.
• Берите в кавычки подписи со спецсимволами: A["Цена: $5 (с налогом)"].
• Добавляйте комментарии с помощью %% в начале строки. При отрисовке они игнорируются.
• Смотрите предпросмотр по ходу работы. Пропущенная стрелка или скобка ломает всю диаграмму, поэтому живой предпросмотр избавляет от гадания. В Markdown Preview Editor диаграмма перерисовывается по мере правки, а кнопка Диаграмма Mermaid в расширенном редакторе вставляет стартовый шаблон.

Как делиться документами с диаграммами

Когда вы экспортируете документ в HTML или PDF, диаграммы попадают в него в виде изображений, поэтому читателю не нужен установленный Mermaid. Для формул рядом с диаграммами прочитайте, как писать формулы в Markdown, а для всего остального — таблиц, списков задач, блоков-предупреждений — держите под рукой шпаргалку по Markdown.