Справочник синтаксиса диаграмм Mermaid
Craft Agent отображает диаграммы Mermaid как тематические SVG. Здесь описан синтаксис для создания диаграмм.
Необязательный YAML Frontmatter
Блоки кода Mermaid могут начинаться с YAML frontmatter. Craft Agent принимает frontmatter для совместимости и отображает синтаксис диаграммы, который следует за ним. Для видимых заголовков диаграмм предпочитайте синтаксис заголовка на уровне диаграммы (например, title "Monthly Revenue" в xychart-beta).
---
title: Example Diagram
---
graph LR
A --> BДиаграммы потоков
Заголовок: graph LR (слева направо, предпочтительно) или graph TD (сверху вниз)
Направления: LR (предпочтительно), RL, TD, TB, BT
Формы узлов
| Синтаксис | Форма |
|---|---|
A[text] | Прямоугольник |
A(text) | Прямоугольник со скруглёнными углами |
A{text} | Ромб (решение) |
A([text]) | Стадион |
A((text)) | Круг |
A[[text]] | Подпрограмма |
A[(text)] | Цилиндр (база данных) |
A{{text}} | Шестиугольник |
A>text] | Асимметричный флаг |
A[/text\] | Трапеция |
A[\text/] | Трапеция (альт.) |
A(((text))) | Двойной круг |
Типы стрелок
| Синтаксис | Стиль |
|---|---|
--> | Сплошная стрелка |
--- | Сплошная линия (без стрелки) |
-.-> | Пунктирная стрелка |
-.- | Пунктирная линия |
==> | Толстая стрелка |
=== | Толстая линия |
<--> | Двусторонняя сплошная |
<-.-> | Двусторонняя пунктирная |
<==> | Двусторонняя толстая |
Подписи рёбер
graph LR
A -->|label text| B
C -- label text --> DПодграфы
graph LR
subgraph Backend
API --> DB
end
subgraph Frontend
UI --> API
end
Client --> UIПодграф с ID
graph TD
subgraph backend-services [Backend Services]
direction LR
API --> Cache
API --> DB
endСтилизация
graph LR
A[Start]:::highlight --> B[End]
classDef highlight fill:#f9f,stroke:#333
style B fill:#bbf,stroke:#333Цепочки рёбер
graph LR
A --> B --> C --> DПараллельные связи
graph LR
A & B --> C & DДиаграммы состояний
Заголовок: stateDiagram-v2
Базовые состояния
stateDiagram-v2
[*] --> Idle
Idle --> Processing: start
Processing --> Complete: done
Processing --> Error: fail
Complete --> [*]
Error --> Idle: retryОписания состояний
stateDiagram-v2
state "Waiting for input" as Waiting
Waiting --> ProcessingКомпозитные состояния
stateDiagram-v2
state "Active" as Active {
Running --> Paused: pause
Paused --> Running: resume
}
[*] --> Active
Active --> [*]: completeПереопределение направления
stateDiagram-v2
direction LR
[*] --> A --> B --> [*]Диаграммы последовательностей
Заголовок: sequenceDiagram
Типы сообщений
| Синтаксис | Значение |
|---|---|
->> | Сплошная линия, сплошной наконечник |
-->> | Пунктирная линия, сплошной наконечник |
-) | Сплошная линия, открытый наконечник (асинхронный) |
--) | Пунктирная линия, открытый наконечник |
-x | Сплошная линия с X (потерянное сообщение) |
--x | Пунктирная линия с X |
Участники
sequenceDiagram
participant C as Client
participant S as Server
participant DB as Database
C->>S: POST /api/users
S->>DB: INSERT user
DB-->>S: OK
S-->>C: 201 CreatedАктивации
sequenceDiagram
Client->>+Server: Request
Server->>+Database: Query
Database-->>-Server: Results
Server-->>-Client: ResponseЗаметки
sequenceDiagram
Alice->>Bob: Hello
Note right of Bob: Bob thinks
Bob-->>Alice: Hi!
Note over Alice,Bob: Conversation completeЦиклы
sequenceDiagram
loop Every minute
Client->>Server: Heartbeat
Server-->>Client: ACK
endАльтернативы
sequenceDiagram
Client->>Server: Request
alt Success
Server-->>Client: 200 OK
else Failure
Server-->>Client: 500 Error
endНеобязательный блок
sequenceDiagram
opt If cached
Server-->>Client: Cached response
endПараллельный блок
sequenceDiagram
par Parallel requests
Client->>ServiceA: Request A
and
Client->>ServiceB: Request B
endДиаграммы классов
Заголовок: classDiagram
Классы с членами
classDiagram
class Animal {
+String name
+int age
+makeSound() void
+move(distance) void
}Модификаторы видимости
| Символ | Значение |
|---|---|
+ | Публичный |
- | Приватный |
# | Защищённый |
~ | Пакет/внутренний |
Связи
| Синтаксис | Значение |
|---|---|
<\|-- | Наследование (extends) |
*-- | Композиция (contains) |
o-- | Агрегация (has) |
--> | Ассоциация |
..> | Зависимость |
..\|> | Реализация (implements) |
-- | Связь (сплошная) |
.. | Связь (пунктирная) |
Кардинальность
classDiagram
Customer "1" --> "*" Order : places
Order "1" *-- "1..*" LineItem : containsПолный пример
classDiagram
class Animal {
<<abstract>>
+String name
+int age
+makeSound()* void
}
class Dog {
+String breed
+bark() void
}
class Cat {
+bool indoor
+meow() void
}
Animal <|-- Dog
Animal <|-- CatАннотации
classDiagram
class Service {
<<interface>>
+start() void
+stop() void
}
class Logger {
<<singleton>>
-instance Logger
+log(msg) void
}Диаграммы ER
Заголовок: erDiagram
Базовые связи
erDiagram
USER ||--o{ ORDER : places
ORDER ||--|{ LINE_ITEM : contains
PRODUCT ||--o{ LINE_ITEM : "is in"Обозначение кардинальности
| Слева | Справа | Значение |
|---|---|---|
|| | || | Ровно один к ровно одному |
|| | o| | Ровно один к нулю или одному |
|| | o{ | Ровно один к нулю или многим |
|| | |{ | Ровно один к одному или многим |
o| | o| | Ноль или один к нулю или одному |
o| | o{ | Ноль или один к нулю или многим |
o{ | o{ | Ноль или много к нулю или многим |
Атрибуты сущностей
erDiagram
USER {
int id PK
string email UK
string name
datetime created_at
}
ORDER {
int id PK
int user_id FK
decimal total
date created_at
}
USER ||--o{ ORDER : placesТипы атрибутов
Основные маркеры атрибутов:
PK— первичный ключFK— внешний ключUK— уникальный ключ
Полный пример
erDiagram
CUSTOMER {
int id PK
string email UK
string name
string phone
}
ORDER {
int id PK
int customer_id FK
date order_date
string status
}
PRODUCT {
int id PK
string name
decimal price
int stock
}
LINE_ITEM {
int id PK
int order_id FK
int product_id FK
int quantity
decimal unit_price
}
CUSTOMER ||--o{ ORDER : places
ORDER ||--|{ LINE_ITEM : contains
PRODUCT ||--o{ LINE_ITEM : "included in"XY-диаграммы
Заголовок: xychart-beta (вертикальные диаграммы) или xychart-beta horizontal (горизонтальные диаграммы)
Используйте XY-диаграммы для метрик, трендов, сравнений и простых столбчатых/линейных визуализаций.
Директивы
| Синтаксис | Значение |
|---|---|
title "Chart Title" | Необязательный заголовок диаграммы |
x-axis [A, B, C] | Категориальная ось X |
x-axis "Label" [A, B, C] | Категориальная ось X с заголовком |
x-axis 0 --> 100 | Числовой диапазон оси X |
x-axis "Label" 0 --> 100 | Числовая ось X с заголовком |
y-axis "Label" 0 --> 100 | Числовая ось Y с заголовком/диапазоном |
bar [10, 20, 30] | Столбчатая серия |
line [12, 18, 28] | Линейная серия |
Столбчатая диаграмма
xychart-beta
title "Monthly Revenue"
x-axis [Jan, Feb, Mar, Apr]
y-axis "Revenue ($k)" 0 --> 100
bar [25, 45, 60, 80]Линейная диаграмма
xychart-beta
title "Latency Trend"
x-axis [Mon, Tue, Wed, Thu, Fri]
y-axis "Latency (ms)" 0 --> 500
line [320, 280, 240, 210, 180]Смешанная столбчатая и линейная диаграмма
xychart-beta
title "Signups vs Activations"
x-axis [Week 1, Week 2, Week 3, Week 4]
y-axis "Users" 0 --> 1000
bar [420, 560, 690, 820]
line [210, 330, 520, 700]Горизонтальная столбчатая диаграмма
xychart-beta horizontal
title "Issue Counts by Severity"
x-axis [Low, Medium, High, Critical]
y-axis "Issues" 0 --> 50
bar [42, 28, 12, 4]Лучшие практики
Предпочитайте горизонтальную (альбомную) ориентацию
ВАЖНО: Используйте горизонтальные макеты (LR, RL) везде, где возможно. Горизонтальные диаграммы значительно удобнее просматривать и навигировать в UI.
- Диаграммы потоков: используйте
graph LR(слева направо), а неgraph TD(сверху вниз) - Диаграммы состояний: добавьте
direction LRпосле заголовка - Диаграммы последовательностей: по умолчанию горизонтальные, изменения не нужны
- Диаграммы классов: для широких иерархий рассмотрите разбиение на несколько горизонтальных диаграмм
- Диаграммы ER: по умолчанию горизонтальные, изменения не нужны
Используйте вертикальные макеты (TD, BT) только когда:
- Диаграмма по своей природе иерархическая (оргструктуры, древовидные структуры)
- Вертикальный макет значительно понятнее горизонтального
- В диаграмме очень мало узлов (не более 3–4)
Держите диаграммы сфокусированными
Одна концепция на диаграмму. Если диаграмма становится сложной, разделите её на несколько диаграмм.
Используйте описательные подписи
graph LR
A[User submits form] --> B{Validation}
B -->|Valid| C[Save to database]
B -->|Invalid| D[Show errors]Выбирайте правильное направление
Горизонтальное (предпочтительно):
- LR (слева направо): ПО УМОЛЧАНИЮ — используйте для потоков, конвейеров, автоматов состояний, процессов и большинства диаграмм
- RL (справа налево): обратные потоки (когда это имеет смысловое значение)
Вертикальное (используйте умеренно):
- TD (сверху вниз): только для иерархий, наследования, оргструктур, где вертикальная структура необходима
- BT (снизу вверх): только для зависимостей, направленных вверх
Проверяйте сложные диаграммы
Используйте инструмент mermaid_validate, чтобы проверить синтаксис перед выводом сложных диаграмм:
mermaid_validate({ code: "graph TD\n A --> B" })Устранение неполадок
Частые ошибки
- Отсутствует направление: всегда указывайте направление в диаграммах потоков (
graph TD, а не простоgraph) - Несбалансированные скобки: убедитесь, что все
[,(,{правильно закрыты - Специальные символы в подписях: используйте кавычки для подписей со специальными символами
- Неверный синтаксис стрелок: проверьте таблицу типов стрелок выше
Экранирование специальных символов
Для подписей со специальными символами заключайте их в кавычки:
graph LR
A["Label with (parentheses)"] --> B["Label with [brackets]"]Нужен такой агент в вашей компании?
Устанавливаем под ключ: настройка на компьютерах сотрудников, единый аккаунт, интеграция с 1С и внутренними системами, обучение команды. Подробнее о внедрении →