oxdraw — это инструмент для создания и редактирования диаграмм с использованием декларативного синтаксиса и возможностью визуального редактирования через веб-интерфейс. Он основан на Mermaid, но позволяет не просто писать код диаграмм, а также настраивать внешний вид (позиции, цвета, линии, стили) прямо в интерфейсе, при этом все изменения автоматически сохраняются обратно в исходный .mmd-файл в виде комментариев.
Благодаря этому диаграммы остаются детерминированными, версионируемыми и совместимыми с другими Mermaid-инструментами.
Ссылки
- Репозиторий: https://github.com/RohanAdwankar/oxdraw
- Mermaid документация: https://mermaid.js.org
Возможности oxdraw
- Создание и редактирование диаграмм в Mermaid-синтаксисе
- Визуальный редактор с поддержкой позиционирования, соединений и цветовых схем
- Автоматическое сохранение изменений в исходный .mmd файл как комментарии
- Rust CLI для компиляции .mmd → изображений (PNG, SVG и др.)
- Веб-интерфейс на React для интерактивного редактирования
Установка
1. Клонирование репозитория
cd oxdraw
2. Установка зависимостей
Rust (для CLI)
Убедитесь, что Rust установлен. Если нет:
Соберите CLI:
Node.js (для веб-интерфейса)
Установите зависимости фронтенда:
npm install
Использование
1. Создание диаграммы
Создайте Mermaid-файл:
2. Запуск веб-интерфейса
Откройте в браузере:
http://localhost:5173
Загрузите example.mmd и начните редактирование — вы можете перемещать узлы, менять цвета, стили и связи.
Все изменения автоматически сохраняются в комментариях в файле, например:
A-->B
B-->C
%% position: A(100,200), B(200,300)
Компиляция диаграмм
После редактирования можно сгенерировать изображения:
Поддерживаются форматы: SVG, PNG и PDF.
Преимущества oxdraw
- Полная совместимость с Mermaid
- Репродуцируемость и контроль версий
- Возможность точной визуальной настройки
- Быстрая интеграция в CI/CD для автогенерации диаграмм в документации
Пример сценария использования
- Создайте архитектурную схему системы в Mermaid
- Откройте её в oxdraw и визуально расставьте блоки
- Сохраните файл и добавьте в Git
- С помощью CLI сгенерируйте финальные изображения для документации
Заключение
oxdraw - это инструмент, который объединяет удобство визуального редактирования с гибкостью декларативного подхода. Он особенно полезен для инженеров, DevOps и технических писателей, которые хотят документировать инфраструктуру, архитектуру систем или CI/CD-пайплайны в виде наглядных и воспроизводимых диаграмм.
С помощью oxdraw вы можете одновременно использовать силу Mermaid и простоту drag-and-drop интерфейса, не теряя контроль над кодом и совместимость с другими инструментами.
Если вы цените детерминизм, прозрачность и контроль версий, oxdraw станет отличным дополнением к вашему инструментарию.
FAQ
- Что делает oxdraw лучше обычного Mermaid?
Обычный Mermaid требует ручного позиционирования элементов через код. oxdraw решает эту проблему, позволяя редактировать диаграмму визуально и автоматически сохранять позиционные изменения обратно в исходный файл как комментарии — без потери совместимости. - Можно ли использовать oxdraw без веб-интерфейса?
Да. CLI-инструмент, написанный на Rust, позволяет компилировать .mmd файлы в изображения без необходимости запускать интерфейс. Это удобно для автоматизации или CI/CD. - Где сохраняются изменения после визуального редактирования?
Все изменения вносятся в исходный .mmd файл в виде комментариев (например %% position: ...). Таким образом, вы можете версионировать и отслеживать различия в Git. - Какие форматы экспорта поддерживаются?
С помощью CLI можно экспортировать диаграммы в SVG, PNG или PDF, что делает oxdraw подходящим для технической документации и презентаций. - Можно ли интегрировать oxdraw в существующие проекты?
Да. oxdraw полностью совместим с Mermaid, поэтому вы можете использовать его в текущих проектах, не меняя формат диаграмм.