Діаграми Mermaid у Markdown: блок-схеми, діаграми послідовностей та інше

Діаграми пояснюють процеси, архітектуру й часові плани краще, ніж абзаци тексту. Але малювати їх у графічному редакторі означає експортувати зображення, зберігати їх поруч із документацією й перемальовувати все, щойно щось змінюється.

Mermaid розв’язує цю проблему: ви описуєте діаграму кількома рядками тексту просто в Markdown-файлі, а переглядач її малює. Діаграма живе в тому самому файлі, видна в diff і оновлюється так само легко, як речення. 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

Дужки навколо підпису визначають форму вузла:

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

Групуйте пов’язані вузли за допомогою 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.