Я часто использую Mermaid — блок-схемы в проектных документах, диаграммы последовательности в README, иногда ER-диаграммы. Диаграммы как код — это удобно: версионируются, сравниваются, не нужно таскать блоки мышкой. Неудобно только то, как результат выглядит.
Встроенные темы функциональны, но цвета выглядят устаревшими. В Mermaid есть полноценная система тем — ставишь theme: 'base' и переопределяешь любые themeVariables. Проблема в рабочем процессе: правишь frontmatter, перерендериваешь, щуришься на результат, угадываешь, какая из 70 с лишним переменных рисует то, что тебе не нравится, и повторяешь.
Точкой кипения стала диаграмма последовательности. Я поменял primaryColor — и блоки actor поменяли цвет вместе с ним. Оказалось, за них отвечает actorBkg. Десять минут на один цвет, и большую часть времени ты просто угадываешь, потому что имя переменной почти ничего не говорит о том, что она закрашивает.
Мне нужно было простое: крутнул переменную — сразу увидел, что она делает.
Так появился mermaid.design: слева код Mermaid, в центре живой превью, справа вся система тем. Каждое изменение перерендеривает диаграмму на месте, и цикл обратной связи сократился с минут до секунд.
Это фасад. А вот модули, которые реально экономят время.
Галерея: все типы диаграмм сразу
Самое неприятное в переменных темы — одна и та же переменная ведёт себя по-разному в разных типах диаграмм. Страница галереи рендерит все 84 шаблона — блок-схемы, диаграммы последовательности, классов, состояний, ER и другие — вживую с твоей текущей темой. Поменял переменную, пролистал галерею — и эффект на каждом типе диаграмм как на ладони. Больше не нужно переключаться между типами туда-сюда. На этом и экономится время.
Переменные темы: значения по умолчанию и наследование на виду
Каждая из 73 переменных показывает своё значение по умолчанию из базовой темы mermaid. Переменные, которые ты не задал явно, получают значок AUTO — с тем значением, которое mermaid выводит во время рендера, и с указанием, откуда оно взялось:
mainBkgследует заprimaryColorprimaryBorderColor— цвет рамки, вычисленный изprimaryColorsecondaryTextColor— инверсияsecondaryColor(для контраста)actorBkgследует заmainBkg— вот и объяснение ловушки из начала: блоки actor поменялись вместе сprimaryColor, потому что существует цепочка наследованияprimaryColor→mainBkg→actorBkg
Когда видишь цепочку, перекраска перестаёт быть угадайкой.
Пресеты: официальные, авторские — и будет больше
21 пресет в один клик: 11 официальных тем mermaid (default, neutral, dark, forest, base и новинки v12 — семейства redux и neo) и 10 авторских пресетов, которые я настроил вручную. У каждого живое мини-превью, и коллекция продолжает расти.
Генерация: один основной цвет — целая палитра
Выбери один базовый цвет — и генератор растянет светлоту в HSL-пространстве вокруг его оттенка (шкала из 8 ступеней), выведя полную палитру, включая вариант для тёмного режима. Самый быстрый способ подогнать диаграмму под фирменный стиль.
Конфигурация рендеринга: не только цвета
Цвета — лишь половина дела. У mermaid есть 438 параметров, влияющих на рендеринг, сгруппированных по типам диаграмм в 34 группы. Несколько примеров:
- Глобальные:
fontFamily,fontSize,wrap(автоперенос текста),look(classic или handDrawn — «от руки») - Блок-схемы:
flowchart.curve(стиль кривых),flowchart.nodeSpacing/flowchart.rankSpacing(отступы узлов/рангов),flowchart.diagramPadding - Диаграммы последовательности:
sequence.actorMargin,sequence.messageMargin,sequence.showSequenceNumbers(нумерация сообщений),sequence.mirrorActors - Круговые:
pie.textPosition,pie.donutHole,pie.legendPosition
Группа, соответствующая текущему типу диаграммы, открывается автоматически.
ASCII-режим: диаграмма как текст
Та же диаграмма может отрисоваться ASCII-артом — копируется в один клик и готова для комментариев в коде, сообщений коммитов или plain-text документов. Пока поддерживается пять типов диаграмм: блок-схемы, последовательности, классы, состояния и ER. Набор символов — Unicode-псевдографика или чистый ASCII.
Подводя итог
Мотивация у mermaid.design простая: официальные цвета тем сложно полюбить, ручная настройка themeVariables отнимает много времени, и мне нужно было место, где каждое изменение сразу видно. Теперь здесь есть живое редактирование переменных с видимыми значениями по умолчанию и наследованием, галерея, показывающая все типы диаграмм разом, официальные и авторские пресеты, генератор, собирающий целую палитру из одного основного цвета, 438 параметров рендеринга и ASCII-режим, превращающий диаграмму в текст.
Если ты тоже борешься с темами Mermaid — попробуй.