В этом материале хочу поделиться небольшой ремаркой о том как в эпоху повального использования markdown привнести в любой документа, а значит и рендер документации векторные схемы для разных случаев. Не секрет, что для генерации контента масса ИИ выпускает ответ в виде markdown разметки, веб-агенты в интерфейсе отрисовывают выдачу в виде качественного HTML-документа, хотя markdown больше про отрисовку структуры статьи (заголовки, списки, сноски, заметки, ссылки, таблицы). За этот год мне пришлось перейти для описания документации в стиль markdown, и mermaid дополнил контент достаточно полно.
Немного теории
Markdown — лёгкий язык разметки для форматирования текста (заголовки, списки, ссылки, таблицы и т.д.) с простым синтаксисом, который конвертируется в HTML. Файлы обычно с расширением .md. Почитать подробнее по ссылке: https://www.markdownguide.org.
Mermaid — инструмент для создания диаграмм и схем (блок-схемы, графы, gantt, sequence и др.) с помощью текстового описания внутри Markdown-блоков. Подробнее в документации непосредственно самого "движка" https://mermaid.js.org/intro/.
А как на практике
На практике все просто:
- Создаете/пишите/генерируете контент в разметке
markdown. - Даете ИИ задачу сгенерировать схему для
mermaidпод раздел вашей статьи, ну или, выбираете тип объекта mermaid и описываете вашу схему согласно его синтаксической форме. - Тут на выбор:
- Либо вставляете в он-лайн рендер https://mermaid.live схему и скачиваете картинку в блоке Actions.
- Либо прописываете на своем сайте JS библиотеку (через cdn или локальную копию) и вставляете свой блок описания схемы согласно документации.
Типы диаграмм (объектов) в Mermaid
| # | Тип диаграммы | Ключевое слово (синтаксис) | Описание | Пример использования |
|---|---|---|---|---|
| 1 | Блок-схема (Flowchart) | flowchart / graph |
Граф из узлов и стрелок, показывающий последовательность шагов или логику. | Алгоритмы, бизнес-процессы, схемы принятия решений |
| 2 | Диаграмма последовательности (Sequence) | sequenceDiagram |
Взаимодействие между участниками во времени (обмен сообщениями). | Диаграммы UML, протоколы API, сценарии работы системы |
| 3 | Диаграмма классов (Class) | classDiagram |
Классы, их атрибуты, методы и отношения между ними (UML). | Проектирование ООП-архитектуры |
| 4 | Диаграмма состояний (State) | stateDiagram-v2 |
Состояния объекта и переходы между ними. | Статусы заказа, состояния машины состояний |
| 5 | ER-диаграмма (Entity Relationship) | erDiagram |
Сущности и связи между ними в базе данных. | Модели данных, проектирование БД |
| 6 | Диаграмма путешествия пользователя (User Journey) | journey |
Этапы взаимодействия пользователя с продуктом и их оценка. | UX-исследования, customer journey map |
| 7 | Диаграмма Ганта (Gantt) | gantt |
Планирование задач во времени, сроки и зависимости. | Управление проектами, дорожные карты |
| 8 | Круговая диаграмма (Pie) | pie |
Доли в процентах, сектора круга. | Статистика, распределение долей |
| 9 | Квадрантная диаграмма (Quadrant) | quadrantChart |
Точки, размещённые по осям X/Y в четырёх квадрантах. | Матрица приоритетов, анализ портфеля (например, важность vs срочность) |
| 10 | Диаграмма требований (Requirement) | requirementDiagram |
Требования, элементы и их связи (по стандарту системной инженерии). | Технические спецификации, ГОСТ/ISO-документация |
| 11 | Git-граф (Gitgraph) | gitGraph |
Графическое представление веток, коммитов и слияний в Git. | Визуализация истории репозитория |
| 12 | Диаграмма C4 | C4Context, C4Container, C4Component, C4Deployment |
Многоуровневое описание архитектуры ПО (контекст, контейнеры, компоненты, развёртывание). | Документирование архитектуры микросервисов |
| 13 | Интеллект-карта (Mindmap) | mindmap |
Иерархическая древовидная схема идей и понятий. | Мозговой штурм, конспекты, структура документа |
| 14 | Лента времени (Timeline) | timeline |
События, расположенные в хронологическом порядке. | История проекта, роадмапы, хронология событий |
| 15 | Диаграмма Санки (Sankey) | sankey-beta |
Потоки данных/ресурсов, где ширина потока пропорциональна его величине. | Энергобалансы, движение трафика, финансовые потоки |
| 16 | XY-диаграмма (Xychart) | xychart-beta |
Графики на координатной плоскости: линии, бары, точки. | Графики метрик, продаж, динамики показателей |
| 17 | Блочная диаграмма (Block) | block-beta |
Блочная компоновка элементов и связей (широкие стрелки, колонки, сетки). | Архитектурные схемы, компоновка модулей |
| 18 | Архитектурная диаграмма (Architecture) | architecture-beta |
Описывает систему как группы связанных сервисов, контейнеров, потоков данных. | Схемы облачной/сетевой инфраструктуры |
| 19 | Диаграмма пакетов (Packet) | packet-beta |
Битовые схемы сетевых пакетов и протоколов. | Разбор заголовков протоколов (TCP/IP, HTTP) |
| 20 | Канбан-доска (Kanban) | kanban |
Доска с колонками и карточками задач (по методологии Kanban). | Управление задачами команды, трекинг проектов |
| 21 | Радарная диаграмма (Radar) | radar-beta |
Многомерные данные в виде «паутины» с осями-показателями. | Сравнение навыков, оценка по нескольким критериям |
Markdown победил потому, что закрыл нишу между «просто текст» и «сложная типографика»: он достаточно выразителен для документации, но настолько прост, что его не нужно «преодолевать». Плюс его подхватили все крупные платформы (GitHub прежде всего), что создало эффект сетевого роста.