Быстрый старт и шпаргалка по диаграммам Mermaid для разработчиков
Диаграммы как код, без лишних сложностей.
Mermaid — это текстовый инструмент для создания диаграмм, предназначенный для тех, кто предпочитает описывать диаграммы текстом, а не перетаскивать блоки на холсте. Он использует синтаксис, похожий на Markdown, для описания блок-схем, диаграмм последовательностей, диаграмм классов, автоматов состояний, временных шкал, диаграмм Ганта, диаграмм сущностей и связей и многого другого.
Для технического блога Mermaid является очень хорошим вариантом по умолчанию. Диаграммы находятся рядом со статьей, их можно просматривать в Git, и их легко обновлять при изменении системы. Статические изображения диаграмм выглядят красиво, пока не произойдет первое изменение архитектуры. Диаграммы Mermaid не идеальны, но они стареют гораздо лучше.
Это руководство представляет собой практическое введение и шпаргалку по Mermaid для разработчиков, технических писателей и владельцев сайтов на Hugo. Оно является частью хабa Инструменты для документации в 2026 году: Markdown, LaTeX, PDF и рабочие процессы печати.
Что такое Mermaid?
Mermaid — это синтаксис диаграмм как кода. Вы пишете небольшой текстовый блок, и Mermaid рендерит его как диаграмму.
Базовая диаграмма Mermaid выглядит так:
этот код:
```mermaid
flowchart TD
A[Write Markdown] --> B[Add Mermaid block]
B --> C[Render page]
C --> D[Publish diagram]
```
Производит диаграмму:
Основная идея проста: исходным материалом диаграммы является обычный текст. Это делает его удобным для поиска, проверки, переносимым и легким для хранения вместе с документацией, которую он объясняет.
Почему стоит использовать Mermaid в техническом блоге?
Mermaid полезен, когда вашей статье нужно больше, чем просто текст, но меньше, чем полноценный инструмент проектирования.
Используйте Mermaid, когда вы хотите объяснить:
- Поток запросов и ответов
- Конвейеры развертывания
- Зависимости сервисов
- Переходы состояний
- Отношения в базе данных
- Путь пользователя
- Шаги сборки
- Логика принятия решений
- Временные рамки проектов
Я бы не использовал Mermaid для каждой визуализации. Скриншоты, наброски архитектуры от руки и отполированные маркетинговые диаграммы по-прежнему находят свое применение. Но для инженерной документации Mermaid часто является наиболее поддерживаемым вариантом.
Быстрый старт Mermaid
Базовое использование в Markdown
В Markdown используйте ограниченный блок кода с mermaid в качестве языка:
```mermaid
flowchart LR
A[Start] --> B[Process]
B --> C[Done]
```
Многие платформы понимают этот формат напрямую. mermaid — это один из специальных идентификаторов языка — наряду с diff, geojson и другими — который определенные рендереры воспринимают как блок первого класса, а не просто как подсветку синтаксиса. Для полного разбора синтаксиса ограниченных блоков и поддерживаемых идентификаторов языка см. Руководство по блокам кода Markdown. Для Hugo рендеринг зависит от вашей темы или конфигурации сайта. Подробнее об этом позже.
Тестируйте диаграммы перед публикацией
Самый простой рабочий процесс:
- Напишите диаграмму в файле Markdown.
- Вставьте ее в живой редактор Mermaid или локальный предварительный просмотр.
- Исправьте ошибки синтаксиса.
- Закоммитьте исходный код Markdown.
- Проверьте финальную отрендеренную страницу.
Это избегает классической проблемы, когда диаграмма работает в одном рендерере, но ломается в другом из-за небольшой детали синтаксиса.
Синтаксис блок-схем
Блок-схемы — самый распространенный тип диаграмм Mermaid. Используйте их для рабочих процессов, алгоритмов, деревьев решений и шагов системы.
Базовая блок-схема
этот код:
```mermaid
flowchart TD
A[User opens website] --> B{Is user logged in?}
B -->|Yes| C[Show dashboard]
B -->|No| D[Show login page]
```
Производит диаграмму:
Направления блок-схем
Блок-схемы Mermaid поддерживают несколько направлений:
TD - сверху вниз
TB - сверху вниз
BT - снизу вверх
LR - слева направо
RL - справа налево
Пример:
этот код:
```mermaid
flowchart LR
Browser --> CDN
CDN --> WebServer
WebServer --> Database
```
Производит диаграмму:
Для статей в блоге LR часто удобнее читать для диаграмм архитектуры. Для пошаговых процессов TD обычно лучше.
Общие формы узлов
этот код:
```mermaid
flowchart TD
A[Rectangle]
B(Rounded rectangle)
C{Decision}
D((Circle))
E[(Database)]
F[[Subroutine]]
```
Производит диаграмму:
Стрелки блок-схем
этот код:
```mermaid
flowchart LR
A --> B
B --- C
C -.-> D
D ==> E
E -- Label --> F
```
Производит диаграмму:
Подграфы
Используйте подграфы для группировки связанных частей системы.
этот код:
```mermaid
flowchart LR
subgraph Client
Browser
end
subgraph Backend
API
Worker
end
subgraph Storage
DB[(PostgreSQL)]
Cache[(Redis)]
end
Browser --> API
API --> DB
API --> Cache
API --> Worker
```
Производит диаграмму:
Подграфы мощны, но используйте их осторожно. Диаграмма с шестью подграфами и двадцатью стрелками обычно является признаком того, что статье нужны две меньшие диаграммы.
Синтаксис диаграмм последовательностей
Диаграммы последовательностей показывают взаимодействие между участниками или сервисами с течением времени.
этот код:
```mermaid
sequenceDiagram
participant User
participant App
participant API
participant DB
User->>App: Click login
App->>API: POST /login
API->>DB: Validate credentials
DB-->>API: User record
API-->>App: Access token
App-->>User: Show dashboard
```
Производит диаграмму:
Общие стрелки последовательностей
-> сплошная линия без стрелки
--> пунктирная линия без стрелки
->> сплошная линия со стрелкой
-->> пунктирная линия со стрелкой
-x сплошная линия с крестом
--x пунктирная линия с крестом
Бары активации
Бары активации делают понятнее, когда участник выполняет работу.
этот код:
```mermaid
sequenceDiagram
participant Client
participant Server
Client->>Server: Request data
activate Server
Server-->>Client: Response
deactivate Server
```
Производит диаграмму:
Альтернативы и условия
этот код:
```mermaid
sequenceDiagram
participant User
participant API
participant Payment
User->>API: Submit order
alt Payment succeeds
API->>Payment: Charge card
Payment-->>API: Approved
API-->>User: Order confirmed
else Payment fails
Payment-->>API: Declined
API-->>User: Show error
end
```
Производит диаграмму:
Диаграммы последовательностей отлично подходят для статей об API. Они показывают не только какие компоненты существуют, но и как они общаются друг с другом.
Синтаксис диаграмм классов
Диаграммы классов полезны для моделей предметной области и отношений объектов.
этот код:
```mermaid
classDiagram
class User {
+string id
+string email
+login()
+logout()
}
class Order {
+string id
+float total
+submit()
}
User "1" --> "*" Order
```
Производит диаграмму:
Отношения классов
<|-- наследование
*-- композиция
o-- агрегация
--> ассоциация
-- ссылка
..> зависимость
..|> реализация
Пример:
этот код:
```mermaid
classDiagram
Animal <|-- Dog
Animal <|-- Cat
User "1" --> "*" Order
Order *-- OrderItem
```
Производит диаграмму:
Диаграммы классов могут быстро стать шумными. В блоге предпочитайте небольшой срез предметной области, а не полную модель приложения.
Синтаксис диаграмм состояний
Диаграммы состояний объясняют, как что-то изменяется с течением времени.
этот код:
```mermaid
stateDiagram-v2
[*] --> Draft
Draft --> Review: submit
Review --> Published: approve
Review --> Draft: request changes
Published --> Archived: archive
Archived --> [*]
```
Производит диаграмму:
Используйте диаграммы состояний для:
- Циклов жизни заказов
- Состояний развертывания
- Потоков аутентификации
- Статуса фоновых задач
- Рабочих процессов публикации контента
Диаграммы состояний недооценены. Они часто объясняют бизнес-логику лучше, чем длинный абзац.
Синтаксис диаграмм сущностей и связей (ER)
Диаграммы сущностей и связей полезны для моделей баз данных.
этот код:
```mermaid
erDiagram
USER ||--o{ ORDER : places
ORDER ||--|{ ORDER_ITEM : contains
PRODUCT ||--o{ ORDER_ITEM : appears_in
USER {
string id
string email
}
ORDER {
string id
datetime created_at
}
PRODUCT {
string id
string name
}
```
Производит диаграмму:
Маркеры отношений ER
|| ровно один
o| ноль или один
}| один или более
}o ноль или более
ER-диаграммы лучше всего подходят, когда они объясняют отношения, а не каждый столбец. Храните детали реализации в миграциях или документации схемы.
Синтаксис диаграмм Ганта
Диаграммы Ганта полезны для временных рамок проектов.
этот код:
```mermaid
gantt
title Documentation Migration Plan
dateFormat YYYY-MM-DD
section Planning
Audit current docs :a1, 2026-06-01, 5d
Define structure :a2, after a1, 3d
section Writing
Rewrite guides :b1, after a2, 10d
Review and publish :b2, after b1, 4d
```
Производит диаграмму:
Диаграммы Ганта полезны в постах о внутреннем планировании, но они могут быстро устаревать. Используйте их, когда сама временная шкала является сутью.
Синтаксис временной шкалы (Timeline)
Временные шкалы хороши для истории релизов, отчетов об инцидентах и сводок проектов.
этот код:
```mermaid
timeline
title API Evolution
2024 : REST API launched
2025 : Webhooks added
2026 : Event streaming introduced
```
Производит диаграмму:
Используйте временную шкалу, когда порядок важнее зависимости. Если вам важна последовательность событий, а не их причинно-следственная связь, временная шкала сохраняет фокус там, где он должен быть, и остается легкой для чтения беглым взглядом.
Синтаксис круговых диаграмм
Круговые диаграммы поддерживаются, но будьте осторожны. Их легко читать, когда есть только несколько категорий и значения явно различаются.
этот код:
```mermaid
pie title Build Time by Step
"Install dependencies" : 35
"Run tests" : 45
"Build assets" : 20
```
Производит диаграмму:
Субъективный совет: если значения близки или категорий больше пяти, используйте таблицу. Хорошо отформатированная таблица сообщает точные числа более честно, чем круговая диаграмма, где секторы выглядят почти идентично.
Синтаксис графов Git
Графы Git могут объяснять стратегии ветвления и потоки релизов.
этот код:
```mermaid
gitGraph
commit
branch feature
checkout feature
commit
commit
checkout main
merge feature
commit
```
Производит диаграмму:
Это полезно для статей о рабочих процессах Git, разработке на основе trunk, ветках релизов и хотфиксах. Если вам нужна быстрая справка по базовым командам ветвления, Шпаргалка GIT охватывает самые распространенные из них наряду с рабочими процессами слияния и перебазирования.
Шпаргалка Mermaid
Типы диаграмм
flowchart TD
sequenceDiagram
classDiagram
stateDiagram-v2
erDiagram
gantt
timeline
pie
gitGraph
mindmap
journey
Основы блок-схем
flowchart TD
A[Text] --> B[Text]
A -->|Label| B
A -.-> B
A ==> B
A --- B
Формы блок-схем
A[Rectangle]
A(Rounded)
A{Decision}
A((Circle))
A[(Database)]
A[[Subroutine]]
A>Flag]
Основы диаграмм последовательностей
sequenceDiagram
participant A
participant B
A->>B: Message
B-->>A: Reply
activate B
deactivate B
Блоки последовательностей
alt condition
else other condition
end
opt optional step
end
loop each item
end
par parallel task
and another task
end
Основы диаграмм классов
classDiagram
class User
class Order
User --> Order
User "1" --> "*" Order
Основы диаграмм состояний
stateDiagram-v2
[*] --> Idle
Idle --> Running
Running --> Done
Done --> [*]
Основы ER-диаграмм
erDiagram
USER ||--o{ ORDER : places
ORDER ||--|{ ORDER_ITEM : contains
Комментарии
Mermaid поддерживает комментарии с помощью %%.
этот код:
```mermaid
flowchart TD
%% This is a comment
A --> B
```
Производит диаграмму:
Использование Mermaid в Hugo
Контент Hugo обычно пишется на Markdown, поэтому Mermaid естественно вписывается в технический блог на базе Hugo. Точная настройка зависит от вашей темы и конфигурации рендеринга Markdown.
Общий шаблон создания контента остается прежним:
```mermaid
flowchart LR
Markdown --> Hugo
Hugo --> HTML
HTML --> Browser
```
Если ваша тема Hugo уже поддерживает Mermaid, это может отрендериться без дополнительной работы. Если нет, вам обычно нужен хук рендеринга, шорткод, парциал или конфигурация темы, которая загружает Mermaid на страницах, содержащих диаграммы Mermaid.
Практичная настройка Hugo должна стремиться к следующим правилам:
- Храните исходный код Mermaid внутри обычных статей Markdown.
- Загружайте Mermaid только на страницах, где он нужен.
- Избегайте глобального JavaScript, если большинство страниц не используют диаграммы.
- Тестируйте диаграммы во время локального предварительного просмотра.
- Храните исходный код диаграмм в читаемом виде в Git.
Для технического блога ограниченные блоки кода обычно лучше, чем пользовательские шорткоды, потому что они более портативны. Если вы позже перенесете контент на GitHub, другой генератор статических сайтов или платформу документации, стандартные ограниченные блоки Mermaid легче переиспользовать.
Лучшие практики Mermaid
Держите диаграммы маленькими
Диаграмма должна прояснять статью, а не заменять ее. Если читателям нужно увеличивать масштаб, диаграмма, вероятно, слишком велика.
Хорошие диаграммы обычно имеют:
- Одну идею
- Четкое направление
- Короткие метки
- Мало пересекающихся линий
- Последовательное именование
Предпочитайте несколько маленьких диаграмм
Вместо одной огромной диаграммы системы используйте несколько сфокусированных диаграмм:
- Поток запросов
- Топология развертывания
- Модель данных
- Цикл жизни состояний
- Путь сбоев
Это лучше для читателей и лучше для мобильных экранов.
Используйте стабильные имена
Используйте имена, которые соответствуют вашему коду, API или документации. Не называйте одну и ту же вещь API, Backend и Server в разных диаграммах, если это действительно не разные концепции.
Подписывайте важные стрелки
Неподписанные стрелки подходят для простых блок-схем. В системных диаграммах метки часто имеют значение.
этот код:
```mermaid
flowchart LR
Web -->|HTTPS request| API
API -->|SQL query| DB
API -->|publish event| Queue
```
Производит диаграмму:
Избегайте хитрого синтаксиса
Mermaid может делать много вещей. Это не значит, что каждой статье нужны все они. Отдавайте предпочтение синтаксису, который будущий сопровождающий сможет быстро понять.
Кавчите метки при необходимости
Если метка содержит символы, которые сбивают Mermaid с толку, оберните ее в кавычки.
этот код:
```mermaid
flowchart TD
A["User clicks /checkout"] --> B["POST /api/orders"]
```
Производит диаграмму:
Это маленькая привычка, которая предотвращает раздражающие сбои рендеринга.
Думайте о темном режиме
Многие сайты на Hugo поддерживают темный режим. Убедитесь, что ваша тема Mermaid или CSS сайта сохраняет диаграммы читаемыми как в светлом, так и в темном оформлении.
Распространенные ошибки Mermaid
Ошибка 1: Слишком много деталей
Плохие диаграммы Mermaid часто пытаются показать каждый крайний случай. Это делает их технически полными, но практически нечитаемыми. Исправление почти всегда одно и то же: разделите диаграмму на две или три меньшие, каждая из которых охватывает одну проблему, чтобы читатели могли следовать логике, не отслеживая десяток пересекающихся стрелок.
Ошибка 2: Длинные метки
Длинные метки создают широкие блоки и некрасивую компоновку.
Вместо этого кода:
```mermaid
flowchart TD
A[The user submits the registration form with their email address and password]
```
Производит диаграмму:
Предпочитайте этот код:
```mermaid
flowchart TD
A[Submit registration form]
```
Производит диаграмму:
Объясняйте детали в абзаце под диаграммой.
Ошибка 3: Неясное направление
Выберите направление и придерживайтесь его. Большинство диаграмм процессов должны использовать TD. Большинство диаграмм архитектуры легче читать с LR.
Ошибка 4: Восприятие Mermaid как инструмента дизайна
Mermaid — это не Figma. Он не предназначен для диаграмм с точностью до пикселя, и попытка заставить его выполнять эту роль приведет только к разочарованию. Его сила — в поддерживаемости, а не в визуальном совершенстве, и этот компромисс намеренный.
Советы по SEO для Mermaid в технических блогах
Диаграммы Mermaid могут сделать технические статьи более полезными, но поисковым системам по-прежнему нужен текст. Не полагайтесь только на диаграммы.
Для SEO-дружественных статей с Mermaid:
- Используйте описательные заголовки H2 и H3.
- Объясняйте каждую диаграмму в邻近ном тексте.
- Включайте важные ключевые слова в обычный текст.
- Делайте примеры кода копируемыми.
- Добавляйте объяснение в стиле alt под сложными диаграммами.
- Используйте лаконичные заголовок и описание в front matter.
- Избегайте скрытия всего смысла внутри отрендеренного SVG.
Диаграмма Mermaid должна поддерживать статью. Она не должна быть единственным местом, где существует важная информация.
Примеры Mermaid для копирования
Поток запросов API
этот код:
```mermaid
sequenceDiagram
participant Client
participant API
participant Auth
participant DB
Client->>API: GET /account
API->>Auth: Validate token
Auth-->>API: Token valid
API->>DB: Load account
DB-->>API: Account data
API-->>Client: 200 OK
```
Производит диаграмму:
Конвейер CI
этот код:
```mermaid
flowchart TD
A[Push commit] --> B[Install dependencies]
B --> C[Run lint]
C --> D[Run tests]
D --> E[Build site]
E --> F[Deploy]
```
Производит диаграмму:
Этот паттерн естественно отображается на реальную конфигурацию CI. Для пошагового синтаксиса рабочих процессов GitHub Actions Шпаргалка GitHub Actions является удобным дополнением, когда вы хотите превратить диаграмму выше в работающий конвейер.
Рабочий процесс публикации
этот код:
```mermaid
stateDiagram-v2
[*] --> Draft
Draft --> Editing
Editing --> Review
Review --> Published
Review --> Editing
Published --> [*]
```
Производит диаграмму:
Простая модель данных
этот код:
```mermaid
erDiagram
AUTHOR ||--o{ POST : writes
POST ||--o{ COMMENT : receives
AUTHOR {
string id
string name
}
POST {
string id
string title
datetime published_at
}
COMMENT {
string id
string body
}
```
Производит диаграмму:
Когда не использовать Mermaid
Не используйте Mermaid, когда:
- Диаграмме нужен точный визуальный макет.
- Дизайн должен точно соответствовать брендовой системе.
- Визуализация в основном декоративная.
- В диаграмме слишком много узлов для чтения.
- Скриншот объяснил бы суть лучше.
- Контент редко меняется и нуждается в полировке больше, чем в поддерживаемости.
Mermaid отлично подходит для живой технической документации. Он менее хорош для презентационных материалов. Для диаграмм документного качества в печатных или PDF-контекстах LaTeX предлагает пакеты, такие как TikZ и pgfplots, которые дают вам гораздо больший контроль над макетом — Шпаргалка LaTeX охватывает включение диаграмм наряду с остальным инструментарием LaTeX.
Финальные мысли
Mermaid — один из лучших инструментов для технического блогинга, потому что он уважает то, как разработчики уже работают: текстовые файлы, Markdown, Git, код-ревью и повторяемые сборки. Для всего остального вокруг диаграмм — заголовков, списков, таблиц, блоков кода — Шпаргалка Markdown является справочным дополнением, которое следует хранить рядом с этим руководством.
Лучшие диаграммы Mermaid — не самые сложные. Это диаграммы, которые делают концепцию очевидной и остаются легкими для редактирования спустя шесть месяцев.
Используйте Mermaid для диаграмм, которые должны жить вместе с вашей документацией. Держите их маленькими, держите их читаемыми и относитесь к ним как к части исходного кода вашей статьи.
