Як створювати красиві діаграми та схеми в Markdown за допомогою Mermaid
🇬🇧 Read this article in English
Будь-який технічний блог, документація чи опис проекту стають у рази зрозумілішими, якщо додати до них візуальну схему. Зазвичай розробники малюють графіки в графічних редакторах (як-от draw.io чи Figma), експортують їх у PNG та додають картинкою.
Але це незручно: при найменшій зміні схеми доводиться переробляти та переекспортувати весь файл.
Вихід є — Mermaid.js. Це інструмент, який дозволяє малювати діаграми та блок-схеми безпосередньо у Markdown-файлах за допомогою простого текстового коду. Браузер сам перетворить цей код на векторне SVG-зображення!
Сьогодні ми розберемо, як підключити Mermaid у вашому блозі та навчимося малювати основні типи схем із реальними прикладами.
Як увімкнути Mermaid у Jekyll (тема Chirpy)
У темі Chirpy підтримка Mermaid вже вбудована з коробки. Щоб увімкнути рендеринг схем на конкретній сторінці чи у статті, вам достатньо додати лише один рядок у метадані (frontmatter) на самому початку файлу:
1
2
3
4
5
---
title: "Назва вашої статті"
# ... інші налаштування ...
mermaid: true
---
Тепер будь-який блок коду з позначкою ````mermaid` буде автоматично малюватися як схема.
Приклад 1. Блок-схеми (Flowcharts)
Блок-схеми — це найпростіший та найпопулярніший тип діаграм. Вони ілюструють алгоритми, мережеву інфраструктуру або процеси.
Код блок-схеми починається з напрямку: flowchart TD (зверху-вниз / Top-Down) або flowchart LR (зліва-направо / Left-to-Right).
Код:
1
2
3
4
5
6
7
8
9
10
11
```mermaid
flowchart TD
Start([Початок]) --> Input[/Вхідні дані/]
Input --> Decision{Чи дані валідні?}
Decision -- Так --> Process[Обробити дані]
Decision -- Ні --> Error[Вивести помилку]
Process --> End([Кінець])
Error --> End
```
Результат на сайті:
flowchart TD
Start([Початок]) --> Input[/Вхідні дані/]
Input --> Decision{Чи дані валідні?}
Decision -- Так --> Process[Обробити дані]
Decision -- Ні --> Error[Вивести помилку]
Process --> End([Кінець])
Error --> End
💡 Зверніть увагу на форми вузлів:
([круглі кути])позначають старт/фініш,[/паралелограм/]— вхід/вихід,[прямокутник]— дію, а{ромб}— умову (розгалуження).
Приклад 2. Діаграми послідовності (Sequence Diagrams)
Цей тип схем ідеально підходить для опису взаємодії між клієнтом, сервером, базою даних чи зовнішніми API при авторизації або обміні даними.
Код:
1
2
3
4
5
6
7
8
9
10
11
12
13
```mermaid
sequenceDiagram
autonumber
Клієнт->>Сервер: Запит на авторизацію (Login/Pass)
Сервер->>База Даних: Перевірка користувача
База Даних-->>Сервер: Користувача знайдено, хеш збігається
rect rgb(0, 150, 255, 0.1)
Note over Сервер: Генерація JWT токена
end
Сервер-->>Клієнт: Успішно! (Повертаємо JWT токен)
```
Результат на сайті:
sequenceDiagram
autonumber
Клієнт->>Сервер: Запит на авторизацію (Login/Pass)
Сервер->>База Даних: Перевірка користувача
База Даних-->>Сервер: Користувача знайдено, хеш збігається
rect rgb(0, 150, 255, 0.1)
Note over Сервер: Генерація JWT токена
end
Сервер-->>Клієнт: Успішно! (Повертаємо JWT токен)
Приклад 3. Діаграми станів (State Diagrams)
Чудово підходять для візуалізації життєвого циклу процесів або станів об’єктів (наприклад, замовлення в інтернет-магазині: Нове -> Оплачене -> Доставлене).
Код:
1
2
3
4
5
6
7
8
9
10
```mermaid
stateDiagram-v2
[*] --> Нове
Нове --> ОчікуєОплати : Створено чек
ОчікуєОплати --> Оплачено : Оплата успішна
ОчікуєОплати --> Скасовано : Тайм-аут 15 хв
Оплачено --> Доставлено : Відправлено поштою
Доставлено --> [*]
Скасовано --> [*]
```
Результат на сайті:
stateDiagram-v2
[*] --> Нове
Нове --> ОчікуєОплати : Створено чек
ОчікуєОплати --> Оплачено : Оплата успішна
ОчікуєОплати --> Скасовано : Тайм-аут 15 хв
Оплачено --> Доставлено : Відправлено поштою
Доставлено --> [*]
Скасовано --> [*]
3 важливі лайфхаки при роботі з Mermaid
Коли ви почнете малювати складніші схеми, ви можете зіткнутися з помилками рендерингу або обрізанням тексту. Тримайте ці правила в голові:
Перенесення тексту (
<br>)
Якщо в блоці забагато тексту, вузол стане дуже широким, а його кінець може обрізатися браузером. Використовуйте HTML-тег<br>для розбиття тексту на декілька рядків:вузол["Назва вузла<br>Додатковий опис або IP"]- Обов’язкові лапки для спецсимволів
Якщо текст у блоці містить двокрапки (:), дужки або пробіли в назвах підгруп, завжди беріть його у подвійні лапки. Інакше Mermaid видасть помилку Syntax error in text:- Правильно:
вузол["Сервер: 192.168.1.1"] - Неправильно:
вузол[Сервер: 192.168.1.1]
- Правильно:
- Стилізація блоків
Ви можете розфарбувати свої схеми, додавши стиль в кінець коду Mermaid (вказується колір фону, обводка та товщина лінії):style вузол_id fill:#ff9900,stroke:#333,stroke-width:2px
Висновок
Mermaid робить ведення документації чи описів проектів суттєво зручнішим. Оскільки діаграми описуються текстом, їх можна зберігати прямо в Git разом із кодом, бачити історію змін (diff) та оновлювати за лічені секунди простим редагуванням тексту.