Редактор блок-схем Mermaid
Блок-схема показывает, как движется процесс: какие есть шаги, где он ветвится и где ветви сходятся обратно. Она уместна, когда суть — порядок решений: деплой, путь запроса, цепочка согласований. Если же суть в том, кто с кем и когда обменивается сообщениями, берите диаграмму последовательности.
Пайплайн деплоя с двумя путями отказа
Большинство блок-схем на этом сайте начинаются именно с такой формы: прямой основной путь, от которого отходят ромбы решений. Обратите внимание на кавычки в предпоследнем узле. Скобки внутри подписи обязательно брать в кавычки — это самая частая ошибка из всех.
flowchart TD
Push[Пуш в main] --> Lint[Статический анализ и типы]
Lint --> Test{Тесты прошли?}
Test -->|Нет| Alert[Уведомить автора коммита]
Test -->|Да| Build[Собрать образ]
Build --> Scan{Сканер без уязвимостей?}
Scan -->|Нет| Block["Остановить релиз (ручная проверка)"]
Scan -->|Да| Deploy[Выкатить в продакшн]
Deploy --> Smoke[Дымовые тесты]
Smoke --> Done[Релиз завершён]Разобранные примеры
1. Минимальная блок-схема
Два узла и стрелка. `TD` — сверху вниз, `LR` — слева направо; схема шире, чем выше, почти всегда читается лучше в `LR`.
flowchart TD
Приём[Принять запрос] --> Ответ[Отправить ответ]2. Ветвление с подписями
Фигурные скобки рисуют ромб. То, что стоит между вертикальными чертами, подписывает ребро, а не узел. Это различие пригодится ниже, в разделе про ошибки.
flowchart TD
Начало[Принять запрос] --> Авторизация{Токен действителен?}
Авторизация -->|Да| Обработка[Выполнить обработчик]
Авторизация -->|Нет| Отказ[Вернуть 401]
Обработка --> Готово[Вернуть 200]3. Пусть форма что-то значит
Формы — самый дешёвый способ добавить информации в блок-схему. Скруглённые концы отмечают начало и конец, ромб — решение, цилиндр — хранилище данных.
flowchart LR
Старт([Запустить задачу]) --> Чтение[(Прочитать из Postgres)]
Чтение --> Есть{Есть новые строки?}
Есть -->|Нет| Конец([Завершить без изменений])
Есть -->|Да| Преобразование[/Преобразовать данные/]
Преобразование --> Запись[(Записать в S3)]
Запись --> Конец4. Подграфы для группировки по владельцу
Подграф заключает связанные узлы в рамку. Больше всего пользы он приносит, когда группирует не по этапам, а по владельцу: как только видно, какая команда или какой сервис за что отвечает, становятся заметны точки передачи.
flowchart TD
subgraph client [Браузер]
UI[Отправить форму]
end
subgraph api [Сервис заказов]
Проверка[Проверить данные]
Сохранение[Сохранить заказ]
end
subgraph async [Фоновые задачи]
Письмо[Отправить подтверждение]
Счёт[Сформировать счёт]
end
UI --> Проверка
Проверка --> Сохранение
Сохранение --> Письмо
Сохранение --> Счёт5. Цикл повторов с ограничением
Блок-схемы хорошо справляются с циклами. Цикл повторов — как раз тот случай, где они по-настоящему полезны: по рисунку сразу видно, есть ли у цикла реальный выход.
flowchart TD
Отправка[Отправить вебхук] --> Ответ{Пришёл 2xx?}
Ответ -->|Да| Успех[Пометить доставленным]
Ответ -->|Нет| Попытки{Меньше 5 попыток?}
Попытки -->|Да| Пауза[Экспоненциальная пауза]
Пауза --> Отправка
Попытки -->|Нет| Очередь[В очередь недоставленных]Справочник синтаксиса блок-схемы
Всё перечисленное относится только к блок-схеме. Особенно стрелки: перенести их в другие типы не получится. `->>` из диаграммы последовательности здесь — синтаксическая ошибка.
| Синтаксис | Значение |
|---|---|
| flowchart TD | Сверху вниз. `TB` — то же самое. Обычное направление чтения процесса. |
| flowchart LR | Слева направо. Есть и `RL`. Для широких и неглубоких потоков. |
| A[Текст] | Прямоугольник — обычный шаг. |
| A(Текст) | Прямоугольник со скруглёнными углами. |
| A([Текст]) | Форма стадиона — по традиции начало или конец. |
| A[(Текст)] | Цилиндр — хранилище данных. |
| A{Текст} | Ромб — решение. |
| A[/Текст/] | Параллелограмм — ввод или вывод. |
| A --> B | Стрелка. |
| A --- B | Линия без наконечника. |
| A -.-> B | Пунктирная стрелка — по традиции асинхронно или необязательно. |
| A ==> B | Жирная стрелка — по традиции основной путь. |
| A -->|текст| B | Подписанное ребро. Со скобками нужны кавычки. |
| A["Текст (со скобками)"] | Подпись в кавычках — нужна для скобок, кавычек и всего, что читается как синтаксис формы. |
| subgraph имя [Заголовок] ... end | Группирует узлы в рамку. Закрывается через `end`. |
| %% комментарий | Строка комментария. Не рисуется. |
Шесть ошибок, которые действительно ломают блок-схему
Все воспроизведены на том движке, который использует сайт (Mermaid 11.12.2). Вставьте сломанный вариант в редактор — и получите ровно описанную ошибку; исправленный рисуется. Самый короткий путь прочитать ошибку Mermaid — посмотреть на её конец: после `got` стоит токен, на котором споткнулся разборщик.
Что вы видите
Parse error, заканчивается на: got 'PS'
Почему
Внутри подписи в квадратных скобках есть открывающая круглая скобка. Круглые скобки — это синтаксис формы: `A(текст)` означает узел со скруглёнными углами, поэтому голая скобка внутри квадратных читается как начало новой формы.
Решение
Возьмите всю подпись в двойные кавычки. Внутри кавычек всё считается текстом.
flowchart TD
A[Повтор (не более 5 раз)] --> B[Готово]flowchart TD
A["Повтор (не более 5 раз)"] --> B[Готово]Что вы видите
Parse error, заканчивается на: got 'STR'
Почему
Посреди подписи стоит двойная кавычка. Разборщик считает её началом строки, а затем натыкается на закрывающую квадратную скобку там, где ждал парную кавычку.
Решение
Возьмите подпись целиком в двойные кавычки, а внутри используйте «ёлочки» или запишите символ как `#quot;`.
flowchart TD
A[Статус — "ожидание"] --> B[Готово]flowchart TD
A["Статус — «ожидание»"] --> B[Готово]Что вы видите
Parse error в строке, где вы назвали узел
Почему
В идентификаторе узла есть пробел. По-русски этого трудно избежать, потому что естественные названия — словосочетания: «сервис авторизации», «база пользователей». Идентификатор — это токен перед стрелкой, и пробел его обрывает, оставляя лишнее слово, которое некуда пристроить.
Решение
Идентификатор — одно слово, читаемый текст — в подписи. Кириллица и буква ё в идентификаторе работают без проблем: мешает только пробел.
flowchart TD
сервис авторизации --> база пользователейflowchart TD
auth[Сервис авторизации] --> db[(База пользователей)]Что вы видите
Parse error, заканчивается на: got 'end'
Почему
Вы использовали `end` как идентификатор узла. В нижнем регистре `end` закрывает подграф, поэтому разборщик видит конец блока там, где ожидал узел. Случается чаще, чем кажется: следуя англоязычным примерам, последний узел по привычке называют `end`, даже когда вся остальная схема на русском.
Решение
Напишите с заглавной буквы или дайте узлу другой идентификатор, а слово перенесите в подпись. `Конец` никаких проблем не вызывает.
flowchart TD
Start[Начать] --> endflowchart TD
Start[Начать] --> Конец[Завершено]Что вы видите
Parse error в подписи ребра между вертикальными чертами
Почему
Внутри подписи ребра есть скобки. К тому, что стоит между `|…|`, применяются те же ограничения, что и к подписи узла: скобки и там синтаксис, а не текст.
Решение
Возьмите в кавычки и подпись ребра.
flowchart TD
A -->|да (всегда)| Bflowchart TD
A -->|"да (всегда)"| BЧто вы видите
Lexical error on line 1. Unrecognized text.
Почему
Неверное направление. Блок-схема принимает только TB, TD, BT, LR и RL; всё остальное падает на лексическом анализе, ещё до чтения узлов. Поэтому ошибка указывает на первую строку, а не на место опечатки.
Решение
Используйте одно из пяти. TD и LR закрывают почти всё.
flowchart СВЕРХУВНИЗ
A --> Bflowchart TD
A --> BЗаметки о рендеринге
Ничего из этого не переписано из документации: всё измерено на том Mermaid 11.12.2, который использует сайт. Это поведение начинает иметь значение, когда схема перестаёт быть игрушечной.
Кириллица работает везде, включая идентификаторы
Проверено: `Начало`, `Проверка`, `Отгрузка` и `Платёж` годятся не только как подписи, но и как идентификаторы узлов — в блок-схеме, диаграмме состояний, диаграмме классов и ER-диаграмме. Буква ё тоже не создаёт проблем. Писать идентификаторы латиницей приходится не из-за движка, а только если вы сами хотите держать их ближе к коду. Единственное, что действительно ломает идентификатор, — пробел.
Подписи переносятся только по пробелам
Измерено: подпись узла расширяется до предела в 276 пикселей viewBox, после чего переносится на новую строку и растёт в высоту примерно на 24 пикселя за строку. Для русского это заметно: `[Validate the request] --> [Send confirmation email]` укладывается в 248 пикселей по ширине и одну строку, а равнозначное `[Проверить запрос] --> [Отправить письмо-подтверждение]` упирается в потолок 276 и добавляет строку. Схема, переведённая с английского, набирает высоту, не набирая ни одного узла. Неожиданная деталь: перенос происходит только по пробелам — одно слово из 40 символов не переносится никогда и растягивает узел до 432 пикселей.
Высота растёт примерно на 105 пикселей на узел, ширина почти не меняется
В схеме сверху вниз три узла дают viewBox около 126×278. При сорока — 135×4126: ширина прибавила 9 пикселей, а высота выросла в пятнадцать раз. Длинная блок-схема — это узкая полоса, которая не помещается ни на один экран. Именно для этого в предпросмотре есть кнопка центрирования. Когда схема слишком вытягивается, переход на `flowchart LR` часто уменьшает соотношение сторон почти вдвое.
Подписи — это HTML, и поэтому экспорт в PNG был сломан
Подписи блок-схемы рисуются как настоящий HTML внутри `<foreignObject>` в SVG. Поэтому в них работают `<br>` и немного Markdown. И поэтому же браузер отказывается переносить такой SVG на canvas: экспорт в PNG на этом сайте долгое время молча отдавал SVG-файл. Теперь перед экспортом схема перерисовывается подписями обычным SVG-текстом, и PNG получается правильным. Плата за это — типографика в PNG чуть отличается от экранной.
Тема меняет цвета, но никогда — геометрию
Одна и та же схема в светлой и тёмной теме даёт полностью совпадающий viewBox. Смена темы ничего не перекомпоновывает и не заставляет подписи вылезать за рамки. Что выглядит странно в тёмной теме, ровно так же выглядит и в светлой.
Когда лучше взять другую диаграмму
Если главное — кто кому что отправляет, и хронология важнее ветвлений, диаграмма последовательности понятнее и остаётся понятной по мере роста. Блок-схема, в которой шесть участников вписаны как названия узлов, — это диаграмма последовательности, которая пока этого не признала.
Если вы описываете не процедуру, а состояния, через которые проходит нечто, возьмите диаграмму состояний. Признак простой: если подписи узлов — состояния («заказ ожидает оплаты», «заказ отгружен»), это конечный автомат; если действия («проверить данные», «отправить письмо»), это блок-схема.
А после сорока узлов, честно говоря, не спасает уже никакая диаграмма. Либо разбейте её на несколько схем с общей точкой входа, либо признайте, что объясняемое слишком сложно для одной картинки. Это тоже полезный вывод.
Другие типы диаграмм
Автор Dominik Malsch · Обновлено: