Mermaid на GitHub: диаграммы прямо в Markdown

GitHub — популярная платформа для обмена кодом — объявил о поддержке нового встроенного содержимого. В Markdown-файлах теперь можно использовать синтаксис Mermaid для простого создания блок-схем, диаграмм последовательностей и других типов диаграмм.

Формат GitHub Flavored Markdown уже поддерживал изображения, списки задач и коды смайликов. Поддержка распространённых диаграмм делает документацию более наглядной и полезной.

Что нового в GitHub

Вы можете вставлять код Mermaid в свои файлы, например в README.md и другие Markdown-документы репозитория. GitHub отрисует диаграмму на основе этого кода. Синтаксис Mermaid — это простой текстовый язык, который описывает элементы диаграммы и связи между ними.

Важно: Mermaid описывает диаграммы в виде текста; вам не нужно загружать отдельные картинки — GitHub рендерит диаграммы в интерфейсе.

Как вставить диаграмму в репозиторий

1. Выберите или создайте Markdown-файл в репозитории (расширения .md или .markdown).
2. Вставьте код Mermaid в файл. Обычно используют блоки кода с тройными обратными кавычками и указанием типа или просто без указания. Примеры ниже.
3. Сохраните изменения и просмотрите файл на GitHub — платформа отобразит диаграмму вместо исходного текста.

Ниже — минимальный пример блок-схемы (форматирование как кодового блока):

graph TD;
  A-->B;
  A-->C;
  B-->D;
  C-->D;

После сохранения такой фрагмент будет отображён как блок-схема.

Типы диаграмм, которые поддерживает Mermaid

Mermaid включает набор распространённых типов диаграмм:

• Flowchart — блок-схемы
• Sequence — диаграммы последовательностей
• Class — диаграммы классов
• State — диаграммы состояний
• Entity Relationship — диаграммы сущностей и связей
• User Journey — путь пользователя
• Gantt — диаграммы Ганта
• Pie — круговые диаграммы
• Requirement — диаграммы требований

Каждый тип имеет собственный синтаксис, отражающий данные, которые он демонстрирует. Примеры ниже помогают начать.

Пример диаграммы последовательностей

Код Mermaid для простой диаграммы последовательностей:

sequenceDiagram
  Bart->>Homer: Don't have a cow, man.

Рендерится как диаграмма последовательностей:

Пример диаграммы состояний

Код для диаграммы состояний процесса (версия v2):

stateDiagram-v2
  [*] --> New
  New --> Ready: admitted
  Ready --> Running: scheduler dispatch
  Running --> Ready: interrupt
  Running --> Waiting: I/O or event wait
  Waiting --> Ready: I/O or event completion
  Running --> Terminated: exit
  Terminated --> [*]

Рендерится как диаграмма жизненного цикла процесса:

Зачем добавлять диаграммы в документацию

• Повышают ясность архитектурных решений и потоков данных.
• Ускоряют понимание кода новым участникам проекта.
• Уменьшают количество вопросов в issue’ах и PRах.
• Легко поддерживать: правка текста проще, чем правка изображения.

Когда не стоит использовать Mermaid

• Если требуется высокодетализированная графика или фирменный стиль — SVG/PNG редакторы дают больше контроля.
• Для больших интерактивных диаграмм с анимацией или сложной вёрсткой Mermaid не подходит.
• Если в документации необходимо гарантированно одинаковое визуальное отображение вне GitHub (в старых ридми-рендерах), лучше хранить экспортированные изображения.

Альтернативы и когда их выбрать

• Статические изображения (PNG/SVG): когда важен точный визуальный стиль.
• Диаграммы в специализированных инструментах (Draw.io, Figma): для сложных UX/дизайн-элементов.
• PlantUML: если в проекте уже используется PlantUML и нужна совместимость с существующими файлами.

Быстрый набор приёмов и мини-методология

1. Начните с простой диаграммы, демонстрирующей ключевые сущности и связи.
2. Сохраните диаграмму в README рядом с соответствующим разделом кода.
3. Добавляйте поясняющие подписи и короткие легенды.
4. Ревью: при PR просите коллег проверять диаграммы на точность и читаемость.
5. Версионируйте ключевые диаграммы вместе с кодом.

Шпаргалка: короткие сниппеты Mermaid

Flowchart (блок-схема):

graph LR
  Start --> Process1 --> Decision{Yes/No}
  Decision -->|Yes| Action1
  Decision -->|No| Action2
  Action1 --> End
  Action2 --> End

Sequence (последовательность):

sequenceDiagram
  Alice->>Bob: Hello Bob, how are you?
  Bob-->>Alice: I am fine, thanks!

State (состояния):

stateDiagram-v2
  [*] --> Idle
  Idle --> Active: start
  Active --> Idle: stop

Gantt (Гантта):

gantt
  dateFormat  YYYY-MM-DD
  section Разработка
  Планирование :done, des1, 2023-01-01, 10d
  Реализация   :active, des2, 2023-01-11, 20d

Копируйте и вставляйте эти фрагменты в свои .md — GitHub отобразит диаграммы.

Чек-листы по ролям

Поддерживать диаграммы проще, если распределить обязанности:

• Для автора кода:
  • Добавить диаграмму в README при изменении архитектуры.
  • Оставить короткое описание под диаграммой.
• Для технического писателя:
  • Проверить читаемость и термины.
  • Обновить легенду и подписи.
• Для ревьюера:
  • Сверить соответствие диаграммы коду.
  • Проверить не загромождена ли диаграмма лишними деталями.

Критерии приёмки

• Диаграмма корректно рендерится на GitHub.
• Основные сущности и связи читаемы без чересчур мелкого текста.
• Подписи и легенда объясняют сокращения и обозначения.
• Диаграмма находится рядом с нарушаемым или описываемым кодом/функцией.

Короткий глоссарий

• Mermaid — текстовый язык для описания диаграмм.
• Флоучарт — блок-схема, отображающая поток действий.
• Sequence — диаграмма, показывающая взаимодействия между участниками.
• State — диаграмма, отображающая переходы состояний объекта.

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

Резюме

Mermaid на GitHub — простой способ добавить наглядность в README и документацию проекта. Это облегчает понимание архитектуры и процессов, ускоряет адаптацию новых участников и уменьшает число уточняющих вопросов. Используйте Mermaid для схем, где текстовая спецификация достаточно выразительна; в сложных визуальных задачах остаются альтернативы в виде статических изображений или специализированных инструментов.

Ссылки для начала: официальная документация Mermaid и встроенная помощь GitHub при редактировании Markdown.