Золотая середина между Mermaid и draw.io

На Hacker News появился свежий проект — Reladraw, текстовый язык описания диаграмм, который занимает нишу между автоматической раскладкой и ручным позиционированием. Вы пишете, где должны стоять элементы, используя слова вроде above-left of или right of, а движок сам вычисляет точные координаты. Никаких пикселей в исходниках. Проект уже набрал более 100 баллов на Hacker News, и сообщество рассматривает его как инженерный ответ на засилье автоматических раскладок в эпоху LLM.

Проблема, которую решает Reladraw

Сегодня у разработчика по сути два варианта для создания диаграмм:

  • Автоматическая раскладка (Mermaid, Graphviz, D2) — вы описываете узлы и связи, движок сам расставляет всё по экрану. Быстро, но без контроля над внешним видом.
  • Ручное позиционирование (draw.io, Excalidraw, Figma) — полный контроль, но каждое изменение требует ручной переработки координат.

Автор хотел совместить преимущества обоих подходов: описывать диаграмму в текстовом языке и при этом сохранять высокую степень контроля над тем, как она выглядит.

ℹ Что такое diagram-as-code?
Diagram-as-code — подход, при котором диаграмма описывается текстом и хранится в системе контроля версий (например, Git). Это позволяет отслеживать изменения, делать code review и автоматически рендерить схемы в CI/CD.

Как работает Reladraw

Reladraw — текстовый формат диаграмм без движка автоматической раскладки, где позиционирование явно задаётся и является детерминированным. Вместо координат используются относительные утверждения:

node app "Web app"
node app.ui  "Interface"
node app.api "API"  below app.ui

node store "Database"  right of app  level with app

edge app.api -> store  "queries"  from: right  to: left

Каждая позиция выражается через отношение к другому элементу — above, below, left of, right of, level with и их комбинации. Поддерживаются выражения вида above X, below X, left of X, right of X, above-left of X, level with X, а также right of A and B — то есть правее бокса, который охватывает оба элемента.

«Arrangement is in the file as sentences, and changing the picture is changing the sentence that says where the thing goes.» — документация Reladraw

Механизм разрешения позиций работает через систему минимальных расстояний: движок решает задачу наикратчайших путей на каждой оси и находит единственное компактное решение — без перебора вариантов. Если добавить новый элемент между двумя существующими, соседи «раздвинутся» ровно настолько, сколько нужно. Удалить — схлопнутся обратно.

Сравнение с популярными инструментами

ИнструментКонтроль позицийТекстовый форматAI-friendlyУстановка
Mermaid❌ авто-раскладка✅⚠️ нет обратной связи✅ нативно в GitHub
Graphviz⚠️ частично✅⚠️⚠️ требует сборки
D2❌ авто-раскладка✅⚠️⚠️ требует сборки
draw.io✅ полный❌ XML/бинарный❌ координаты✅ браузер
Reladraw✅ относительный✅✅ читаем агентом✅ браузер/npm

Mermaid рендерится нативно на GitHub, GitLab и Notion — D2 не рендерится ни на одной из этих платформ. Reladraw пока тоже требует отдельного шага сборки, но работает прямо в браузере через онлайн-песочницу без установки.

Почему это важно для AI-агентов

Reladraw открыто проектировался с учётом работы LLM-агентов (Large Language Model — большие языковые модели). Проблема существующих инструментов в том, что:

  • В Mermaid/D2 агент описывает связи, но не видит финальную раскладку — нужен рендер-цикл, который возвращает картинку, а не список ошибок.
  • В draw.io агент должен разобрать пиксельные координаты, чтобы понять, что где находится, — это дорого и ненадёжно.
💡 Для разработчиков с AI-инструментами

Reladraw поставляется с готовым «скиллом» для AI-агентов. Одна команда добавляет синтаксис языка в контекст Claude Code, Cursor, Copilot и других:

npx skills add reladraw/reladraw -g

Для конкретного агента: npx skills add reladraw/reladraw -g -a claude-code

С Reladraw агент может перечитать свой же файл и убедиться, что база данных находится под API, а четыре машины подключены к хабу синхронизации — всё это читается как текст, без рендеринга.

Текущее состояние и ограничения

Проект находится на стадии v0.5.0 — ранняя, но рабочая версия: парсер, резолвер и SVG-рендерер на TypeScript без рантайм-зависимостей.

npm install -g reladraw
reladraw diagram.reladraw -o diagram.svg

Версия 0.5.0 поддерживает 13 пресетных тем: light, dark, Solarized, Gruvbox, Catppuccin, Nord, Dracula, высококонтрастную и печатную.

⚠ Что ещё не готово
  • Диагностика: инструмент либо рендерит, либо падает с ошибкой — не объясняет, что не так с успешно отрисованной диаграммой.
  • Маршрутизация рёбер: линия между узлами пока прямая и может перекрывать другие элементы.
  • Библиотека иконок: набор форм и иконок ограничен.
  • Синтаксис нестабилен — ожидайте изменений.

Как это работает изнутри


graph LR
    A[Текстовый файл .reladraw] --> B[Парсер]
    B --> C[Резолвер позиций]
    C --> D[Система минимальных расстояний]
    D --> E[Детерминированное решение]
    E --> F[SVG-рендерер]
    F --> G[Готовый SVG]

Каждый «gap» (промежуток) — это минимальное, а не абсолютное расстояние. Это позволяет добавлять и убирать элементы без ручной корректировки остальных. Алгоритм решает всю систему целиком от начала при каждом изменении — не патчит уже готовую раскладку.

Итог

Reladraw — разработанный для разработчиков инструмент создания диаграмм, отражающий устойчивый интерес сообщества к нишевым утилитам и предметно-ориентированным языкам. Инструмент занимает реальную нишу: когда вам важно, как именно выглядит диаграмма, но вы не хотите тащить координаты из draw.io. Особенно актуально для систем, где схемы генерируются или редактируются AI-агентами — текстовое представление позиций принципиально проще для машинного чтения и записи, чем пиксели.

Попробовать можно прямо в браузере: reladraw.github.io/reladraw