Mermaid: схемы из текста — мастерская и 9 практических примеров

Mermaid на практике: девять схем для процессов, API, базы данных и планирования. Живой редактор, темы, масштаб, SVG и исходники .mmd, полный проект для Windows, Linux и VPS.

Mermaid: схемы из текста для документации и интерфейсов

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

Исходник можно хранить рядом с кодом, обсуждать на ревью и изменять обычным редактором. Когда появляется новый этап заявки, достаточно добавить узел и связь. Когда меняется обмен API, исправляется соответствующая строка последовательности. Это удобно для README, внутренней базы знаний, технического задания, статьи и обучения нового участника команды.

В материале используется Mermaid 12.3.0 и собственная мастерская с девятью видами диаграмм. Все схемы действительно строятся в браузере из редактируемого текста. Вы можете изменить пример, переключить тему, рассмотреть результат и скачать SVG вместе с исходным файлом. Проект содержит код интерфейса, сборку и тесты для повторения на своём сайте.

Мини-мастерская: девять задач, которые можно попробовать сразу

Начните с маршрута заявки: измените подпись решения или добавьте согласование. Нажмите «Построить схему» либо Ctrl+Enter. Затем переключитесь на обмен API, состояния заказа или связи CRM. Каждый пример сопровождается объяснением практического применения и границы: диаграмма описывает систему, но сама не выполняет её работу.

Редактор принимает до двенадцати тысяч символов и двухсот строк. Изменение текста делает предыдущий результат неактуальным, поэтому ссылки скачивания появляются после нового успешного построения. При синтаксической ошибке вы увидите сообщение и сможете исправить исходник. Кнопка возврата примера помогает продолжить эксперимент с рабочего состояния.

На странице доступны четыре темы, масштаб и прокрутка широкого изображения. SVG пригодится для документации и презентации, а файл .mmd сохранит редактируемое описание. Изменения не сохраняются после перезагрузки вкладки: скачайте исходник перед уходом. Если встроенная область тесная, откройте мастерскую отдельной вкладкой и работайте с ней как с небольшим инструментом.

Установка, версии и локальная сборка без CDN

В проекте закреплены Mermaid 12.3.0, Bootstrap 5.3.8 и DOMPurify 3.4.17. Для сборки используется Node.js 24.15 или новее, а готовый результат находится в public. Библиотеки поставляются локальными файлами: мастерская не зависит от внешнего CDN при открытии схемы. Node.js нужен для разработки и тестов, но не обязателен серверу, раздающему готовую статику.

Исходные сцены расположены в src/scenes.js, обработчики интерфейса — в src/app.js, ограничения ввода — в отдельном модуле guard. Такое разделение упрощает адаптацию: можно заменить учебные процессы своими и сохранить редактор, экспорт и обработку ошибок. HTML5 и Bootstrap отвечают за привычные элементы формы, а Mermaid — за изображение.

В готовом архиве используйте npm ci, чтобы установить версии из lockfile. Обновление зависимости выполняйте отдельно и повторяйте проверки всех типов схем. Автоматическая раскладка может измениться между версиями даже при прежнем исходном тексте, поэтому одной проверки успешного npm install недостаточно.

npm install --save-exact mermaid@12.3.0
# В готовом проекте:
npm ci --ignore-scripts
npm run build
npm test

Базовый синтаксис: идентификатор, подпись и связь

Первая строка задаёт тип диаграммы. Для блок-схемы можно выбрать направление сверху вниз или слева направо. Далее описываются узлы и связи. Идентификатор узла лучше делать коротким и стабильным, а понятный человеку текст помещать в подпись. Тогда переименование этапа не потребует менять каждую стрелку, которая на него ссылается.

В простом примере A и B — технические идентификаторы, а «Новая заявка» и «Проверка» — видимые названия. Стрелка показывает связь. Подпись на стрелке полезна, когда из решения выходят разные варианты: «Да», «Нет», «Истёк срок». Без подписей даже аккуратная схема может оставаться неоднозначной.

Начинайте с нескольких узлов. Сначала убедитесь, что схема отражает правильный процесс, затем добавляйте ветки, группы и оформление. Большое количество форм и цветов не исправляет неверную логику. Если подпись становится длинным абзацем, перенесите объяснение в текст рядом, а в узле оставьте короткое действие.

flowchart LR
  A["Новая заявка"] --> B["Проверка"]
  B --> C{"Можно выполнить?"}
  C -->|Да| D["Назначить мастера"]
  C -->|Нет| E["Уточнить условия"]

Как браузер превращает описание в SVG

Приложение инициализирует Mermaid, проверяет текст и вызывает render с уникальным идентификатором диаграммы. Библиотека возвращает SVG. В нашей мастерской результат дополнительно очищается DOMPurify, после чего вставляется в область предпросмотра. Пользователь видит изображение, построенное именно из текущего описания.

Проверка parse полезна для понятной обработки синтаксической ошибки, однако она не гарантирует удачную геометрию. Схема может быть формально корректной и при этом слишком широкой или перегруженной. Поэтому работа с Mermaid включает две проверки: правильность описания и удобство итогового изображения.

Построение асинхронное. Интерфейс блокирует повторный запуск на время операции, чтобы несколько результатов не сменяли друг друга в случайном порядке. В большом приложении можно использовать номер запроса или отменять устаревшие вычисления отдельной архитектурой. Важно показывать, когда описание изменилось, а результат ещё соответствует предыдущей версии.

import mermaid from 'mermaid';
mermaid.initialize({
  startOnLoad: false,
  securityLevel: 'strict',
  look: 'classic',
  layout: 'dagre',
  htmlLabels: false
});
await mermaid.parse(source);
const { svg } = await mermaid.render('diagram-1', source);
// Перед вставкой применять политику очистки приложения.

Пример 1. Flowchart: маршрут заявки сервисной компании

Блок-схема отвечает на вопрос, какие действия выполняются и где принимаются решения. В примере новая заявка проверяется на полноту данных. Если информации хватает, назначается мастер; если нет, запрос возвращается на уточнение. После выполнения работы клиент получает акт. Такую схему удобно обсуждать с менеджером до проектирования экранов CRM.

Попробуйте добавить согласование стоимости между проверкой и назначением. Затем подумайте, что происходит при отказе клиента. Схема быстро показывает отсутствующие переходы: может оказаться, что процесс умеет двигаться вперёд, но не предусматривает отмену или повторную проверку. Это полезный результат обсуждения, даже если интерфейс ещё не нарисован.

Flowchart не запускает процесс и не назначает исполнителя. Для автоматизации нужны серверные правила, права пользователей и обработка событий. Диаграмма становится общей моделью, которую сравнивают с реализацией. Подписи стрелок и короткие действия помогают людям с разной технической подготовкой одинаково понимать маршрут.

flowchart TD
  accTitle: Маршрут заявки сервисной компании
  accDescr: Заявка проверяется, затем назначается мастеру или возвращается на уточнение.
  A["Новая заявка"] --> B{"Данных достаточно?"}
  B -->|Да| C["Назначить мастера"]
  B -->|Нет| D["Уточнить у клиента"]
  D --> B
  C --> E["Выполнить работу"]
  E --> F["Отправить акт"]

Пример 2. Sequence diagram: интерфейс, API и очередь

Диаграмма последовательности показывает участников и сообщения между ними во времени. В примере интерфейс заказывает отчёт, API ставит задачу в очередь и сразу возвращает идентификатор. Обработчик готовит файл отдельно, а интерфейс позже запрашивает состояние. Это помогает объяснить, почему ответ 202 ещё не означает готовность документа.

Измените пример: добавьте запрос статуса, ошибку обработки или повторную проверку. Сравните два варианта — долгое ожидание одного HTTP-запроса и фоновую задачу. В таком обсуждении удобно уточнять контракт API: что возвращается при создании, где появляется ссылка и как пользователь узнает о неуспехе.

Схема не является записью настоящего сетевого обмена. Она отражает выбранный сценарий, а реальное поведение подтверждается логами и тестами сервиса. Для практической реализации очереди можно обратиться к материалу о BullMQ. Mermaid помогает объяснить взаимодействие компонентов и увидеть недостающий шаг.

sequenceDiagram
  accTitle: Фоновая генерация отчёта
  participant UI as Интерфейс
  participant API as API сервиса
  participant Q as Очередь
  participant W as Обработчик
  UI->>API: POST /reports
  API->>Q: Добавить задание
  API-->>UI: 202 + идентификатор
  Q->>W: Взять задание
  W->>API: Сохранить результат
  UI->>API: GET /reports/42
  API-->>UI: Ссылка на файл

Пример 3. State diagram: допустимые состояния заказа

Список статусов сам по себе не объясняет, как объект переходит между ними. Диаграмма состояний добавляет направления и события. Заказ начинается как черновик, ожидает оплату, затем переходит к исполнению и завершению. Отмена предусмотрена отдельной веткой. Такая модель полезна перед созданием кнопок «Оплатить», «Начать работу» и «Закрыть заказ».

Попробуйте добавить повторную оплату или возврат на доработку. Проверьте, какие переходы допустимы для клиента, менеджера и фонового обработчика. Если две стороны могут одновременно менять статус, одной красивой схемы недостаточно: потребуется проверка текущего состояния и согласованности на сервере.

Mermaid не создаёт исполняемую машину состояний. Обозначения служат документацией. Чтобы модель не устаревала, храните её рядом с правилами переходов и обновляйте вместе с изменением бизнес-логики. На ревью полезно проверять не только новый успешный путь, но и отмену, повтор, истечение времени и действия после завершения.

stateDiagram-v2
  accTitle: Жизненный цикл заказа
  [*] --> Draft
  Draft --> AwaitingPayment: Отправить
  AwaitingPayment --> Paid: Оплата подтверждена
  AwaitingPayment --> Cancelled: Отмена
  Paid --> InProgress: Назначен исполнитель
  InProgress --> Completed: Работа принята
  Completed --> [*]
  Cancelled --> [*]

Пример 4. ER: клиенты, заявки и работы в CRM

ER-диаграмма показывает сущности, поля и кратность связей. В примере клиент создаёт заявки, а каждая заявка содержит работы. Поле client_id связывает заявку с клиентом, request_id — работу с заявкой. Денежная сумма хранится в копейках, чтобы модель явно выражала единицу измерения и не оставляла её догадкой читателя.

Измените связь и обсудите последствия. Может ли заявка существовать без клиента? Допускается ли заявка без работ? Что происходит при удалении клиента? Диаграмма помогает сформулировать вопросы, но ответы должны появиться в схеме настоящей базы: внешних ключах, ограничениях, индексах и правилах приложения.

Пометки PK и FK в Mermaid являются подписями, а не командами создания таблиц. Код SQL из этой схемы автоматически не выполняется. Для документации полезно указывать, описывается ли текущая база или планируемая модель. Иначе команда может принять желаемую архитектуру за уже действующие гарантии хранилища.

erDiagram
  CLIENT ||--o{ REQUEST : creates
  REQUEST ||--|{ WORK_ITEM : contains
  CLIENT {
    int id PK
    string name
    string email
  }
  REQUEST {
    int id PK
    int client_id FK
    string status
  }
  WORK_ITEM {
    int id PK
    int request_id FK
    int amount_kopecks
  }

Пример 5. Gantt: зависимости задач при выпуске сервиса

Диаграмма Ганта показывает работы на временной шкале и зависимости между ними. В учебном плане сначала уточняются требования и создаётся прототип, затем параллельно разрабатываются API и интерфейс. Тестирование начинается после обеих веток, а публикация отмечена вехой. Так можно объяснить, почему задержка одной части сдвигает общий выпуск.

Измените длительность интерфейса и посмотрите на последующие этапы. Затем проверьте предположение о параллельности: если один разработчик делает обе задачи, нарисованные рядом полосы не создают второго исполнителя. План должен учитывать ресурсы, выходные, согласования и реальные ограничения команды.

Даты и состояния в примере учебные. Mermaid не получает автоматически прогресс из трекера задач и не пересчитывает производственный план по событиям проекта. Для регулярной отчётности потребуется источник данных и правило обновления описания. Диаграмма полезна для обсуждения зависимостей, но точность картинки определяется точностью исходных предположений.

gantt
  title Выпуск клиентского кабинета
  dateFormat YYYY-MM-DD
  axisFormat %d.%m
  excludes weekends
  section Подготовка
  Требования :done, req, 2026-11-02, 3d
  Прототип :done, ui, after req, 2d
  section Разработка
  API :active, api, after ui, 5d
  Интерфейс :front, after ui, 6d
  section Проверка
  Тестирование :test, after api front, 3d
  Публикация :milestone, after test, 0d

Пример 6. User journey: где клиенту неудобно

Путь пользователя помогает рассмотреть сервис глазами человека. В примере клиент выбирает услугу, узнаёт цену, заполняет заявку, согласует время и получает результат. Оценки показывают предполагаемую удобность этапов. Самое слабое место — согласование времени, где участвуют клиент и менеджер.

Попробуйте улучшить этот этап: добавить выбор свободного окна, уведомление о прибытии или понятный статус подтверждения. Затем измените оценку в схеме и сформулируйте, каким исследованием вы проверите улучшение. Число от одного до пяти должно опираться на наблюдение, интервью или явно обозначенную гипотезу.

Диаграмма не доказывает, что пользователь действительно испытывает показанную эмоцию. Она помогает организовать обсуждение и найти вопросы для исследования. Не смешивайте в одной карте ожидания команды и измеренные результаты без подписи источника. В статье или презентации полезно пояснить, кто оценивал этапы и когда модель обновлялась.

journey
  title Запись на обслуживание
  section Выбор
    Найти услугу: 4: Клиент
    Узнать цену: 3: Клиент
  section Оформление
    Заполнить заявку: 4: Клиент
    Согласовать время: 2: Клиент, Менеджер
  section Результат
    Принять работу: 5: Клиент
    Получить документы: 3: Клиент, Менеджер

Пример 7. Class diagram: ответственность модулей

Диаграмма классов удобна, когда нужно объяснить связи между частями приложения. В примере RequestService создаёт и завершает заявки, Repository отвечает за хранение, PriceCalculator — за расчёт, Notifier — за уведомления. Такой рисунок помогает увидеть, не сосредоточилось ли слишком много ответственности в одном объекте.

Добавьте новый канал уведомлений и подумайте, какой модуль должен измениться. Если приходится переделывать расчёт стоимости ради отправки письма, границы ответственности могут быть выбраны неудачно. Диаграмма полезна на архитектурном ревью, особенно когда участники ещё не знакомы со всем исходным кодом.

Названия методов и зависимости в схеме должны соответствовать обсуждаемой версии приложения. Mermaid не проверяет наличие классов в репозитории и не обеспечивает типизацию. Слишком подробный рисунок со всеми приватными методами быстро становится нечитаемым; для объяснения решения обычно важнее публичные контракты и основные направления зависимости.

classDiagram
  class RequestService {
    +createRequest(data)
    +completeRequest(id)
  }
  class RequestRepository {
    +save(request)
    +findById(id)
  }
  class PriceCalculator {
    +calculate(items)
  }
  class Notifier {
    +sendStatus(request)
  }
  RequestService --> RequestRepository
  RequestService --> PriceCalculator
  RequestService --> Notifier

Пример 8. GitGraph: feature, hotfix и выпуск

GitGraph показывает условную историю коммитов, веток и слияний. В примере работа над формой идёт в feature, а срочное исправление создаётся отдельной веткой hotfix. Затем изменения объединяются в main и появляется релиз. Это удобно для обучения и обсуждения правил команды.

Измените порядок слияний и объясните, какие проверки должны происходить перед каждым шагом. Где запускаются тесты, кто делает ревью, как исправление попадает в ещё не завершённую feature-ветку? Схема помогает задавать эти вопросы без необходимости показывать большой реальный репозиторий с лишними деталями.

Mermaid рисует заданную историю и не запускает Git. Она не проверяет, возникнет ли конфликт, сохраняется ли нужный коммит после rebase и соответствует ли диаграмма фактическому состоянию веток. Для анализа настоящей истории используйте инструменты репозитория, а GitGraph оставляйте для объяснения выбранного процесса или конкретного сценария.

gitGraph
  commit id: "Старт"
  branch feature
  checkout feature
  commit id: "Форма"
  commit id: "Тесты"
  checkout main
  branch hotfix
  commit id: "Исправление"
  checkout main
  merge hotfix
  merge feature
  commit id: "Релиз"

Пример 9. Mindmap: границы сервиса и MVP

Карта мыслей помогает собрать возможности вокруг центральной темы. В учебной CRM выделены клиент, менеджер и администратор. У каждой роли есть несколько задач: заявки, история работ, расписание, справочники и резервные копии. Такая структура удобна на раннем этапе, когда команда ещё договаривается о границах продукта.

Уберите функции, которые не нужны первому выпуску, и сравните оставшийся объём. Затем проверьте, не спряталась ли сложная задача под коротким названием. Например, «Документы» может означать простой список файлов или полноценное согласование и подписание. Карта помогает выявить области, но не заменяет их последующее описание.

В mindmap вложенность задаётся отступами. Изменение отступа может поменять смысл связи, даже если сами слова остались прежними. Сначала сформулируйте иерархию, затем занимайтесь оформлением. Для оценки проекта дополните карту приоритетами, критериями готовности и ограничениями, которые нельзя выразить одной веткой.

mindmap
  root((Сервисная CRM))
    Клиент
      Новая заявка
      История работ
      Документы
    Менеджер
      Расписание
      Назначение мастера
      Комментарии
    Администратор
      Пользователи
      Справочники
      Резервные копии

Темы и раскладка: как получить предсказуемый стиль

В мастерской доступны светлая, зелёная, тёмная и нейтральная темы. Они позволяют подобрать изображение под документ или интерфейс. Выбранная тема применяется при новом построении. При экспорте проверьте контраст текста и линий на том фоне, где SVG будет использоваться, особенно для тёмного варианта.

Проект явно задаёт classic и dagre, чтобы не полагаться на меняющиеся значения по умолчанию. Автоматическая раскладка экономит время, но не обещает одинаковое расположение элементов при любой версии библиотеки. Если внешний вид важен для публикации, закрепляйте версии и визуально проверяйте результат после обновления.

Цвет должен помогать читать смысл, а не быть единственным носителем информации. Разные исходы решения лучше подписать словами. Большое количество ручных стилей усложняет поддержку текста и иногда маскирует проблему структуры. Для документации чаще достаточно ограниченной палитры, ясных подписей и разумного размера схемы.

mermaid.initialize({
  startOnLoad: false,
  securityLevel: 'strict',
  theme: 'forest',
  look: 'classic',
  layout: 'dagre',
  htmlLabels: false
});

Доступность: заголовок, описание и текст рядом со схемой

Изображение должно быть понятно не только человеку, который видит все стрелки. Mermaid поддерживает доступный заголовок и описание через accTitle и accDescr для подходящих типов диаграмм. Они помогают передать назначение схемы и её основную логику. В первых примерах мастерской эти строки уже добавлены.

Краткое текстовое объяснение рядом остаётся полезным даже при наличии доступных атрибутов. Оно может сформулировать вывод: заявка возвращается на уточнение при нехватке данных или отчёт готовится асинхронно после ответа API. Читателю не приходится самостоятельно восстанавливать весь смысл из геометрии.

При внедрении проверьте клавиатуру, фокус и сообщения об ошибках. Пользователь должен суметь изменить описание, запустить построение и скачать исходник без мыши. Не объявляйте диаграмму полностью доступной только из-за двух атрибутов: сложные связи, порядок чтения и конкретный экранный диктор требуют отдельной проверки на реальном интерфейсе.

flowchart TD
  accTitle: Проверка заявки
  accDescr: Полная заявка передаётся мастеру, неполная возвращается клиенту.
  A["Заявка"] --> B{"Данные полные?"}
  B -->|Да| C["Мастер"]
  B -->|Нет| D["Уточнение"]

Пользовательский ввод, strict и дополнительная очистка SVG

Редактор диаграмм принимает текст, который превращается в разметку изображения. Поэтому настройки безопасности являются частью интеграции. В мастерской используется securityLevel strict, отключены HTML-подписи, init-директивы и frontmatter. Пользователь меняет тему через отдельный контрол, а не переопределяет конфигурацию произвольным текстом.

Возвращённый SVG дополнительно проходит DOMPurify с профилем SVG. Запрещены foreignObject, ссылки и соответствующие атрибуты. Такая политика соответствует задаче статьи: нужны схемы для просмотра и экспорта, а интерактивные внешние переходы не требуются. В другом приложении политика должна быть определена явно, а не ослаблена ради исчезновения ошибки.

Дополнительно мастерская проверяет разобранные узлы до render и отклоняет изображения img. Это важно: библиотека может начать загрузку картинки ещё во время построения, когда финальный SVG пока не очищен. CSP страницы блокирует внешние изображения и сетевые соединения, сохраняя локальные модули и необходимые стили. Настройки CSP страницы не включаются автоматически в экспортированный SVG.

Очистка разметки не ограничивает вычислительную сложность раскладки. Большой или специально подготовленный граф может нагружать браузер даже без опасного HTML. Для публичного сервиса с недоверенным вводом нужны отдельная изоляция выполнения и внешние лимиты. Ограничение длины текста полезно, но не является гарантией предельного времени CPU.

const cleaned = DOMPurify.sanitize(svg, {
  USE_PROFILES: { svg: true, svgFilters: true },
  FORBID_TAGS: ['foreignObject', 'a'],
  FORBID_ATTR: ['href', 'xlink:href']
});
container.innerHTML = cleaned;

Экспорт SVG и .mmd: сохраняйте результат и исходник

SVG удобен для вставки в документацию: векторное изображение можно увеличивать без потери резкости. Файл .mmd хранит текст, из которого схема построена. Это разные результаты. Скачанный SVG не обязан содержать редактируемое Mermaid-описание, поэтому для дальнейшей работы сохраняйте оба файла.

Мастерская создаёт ссылки только после успешного построения текущего текста. Если вы изменили исходник, старые ссылки скрываются до обновления результата. Такой порядок помогает не скачать изображение от предыдущей версии по ошибке. Автокопирование описания имеет запасной путь: при запрете Clipboard API текст выделяется для обычного копирования.

Перед передачей изображения в другой инструмент откройте файл отдельно и проверьте подписи, размеры и фон. Некоторые редакторы по-разному обрабатывают SVG, шрифты и встроенные стили. Для печати или растрового формата может понадобиться отдельный экспорт, но исходный .mmd всё равно стоит хранить рядом как редактируемый источник.

const svgBlob = new Blob([serializedSvg], {
  type: 'image/svg+xml;charset=utf-8'
});
const sourceBlob = new Blob([source], {
  type: 'text/plain;charset=utf-8'
});
svgLink.href = URL.createObjectURL(svgBlob);
sourceLink.href = URL.createObjectURL(sourceBlob);
// Отзывать прежние Object URL при замене результата.

Мобильный экран: масштаб, прокрутка и понятные действия

Большая схема редко помещается на телефон без уменьшения текста до нечитаемого размера. Поэтому интерфейс должен позволять увеличивать результат и прокручивать его внутри отдельной области. В мастерской редактор и изображение располагаются вертикально на узком экране, а элементы управления сохраняют подписи и заметную область нажатия.

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

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

Производительность и границы большой диаграммы

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

В мастерской ограничены длина текста, число строк и количество связей в конфигурации. Рендеринг выполняется на главном потоке браузера. Поэтому особенно сложная допустимая схема всё равно может временно задержать интерфейс; обычный таймер в том же потоке не гарантирует своевременную остановку вычисления.

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

Windows: установка и локальная мастерская

Распакуйте проект в отдельную папку и откройте PowerShell в её каталоге. Проверьте Node.js версии 24.15 или новее. В готовом архиве зависимости уже закреплены, поэтому команда npm ci восстанавливает ожидаемую среду. Затем выполните сборку, тесты и запуск локального сервера.

Адрес по умолчанию — 127.0.0.1:8171. Сервер слушает только локальный интерфейс и предназначен для разработки. Не открывайте index.html двойным щелчком через file://: модульным файлам и загрузке ресурсов нужен предсказуемый HTTP-контекст. Если порт занят другим сервисом, задайте свободный через PORT.

После запуска выберите все девять сцен и скачайте хотя бы один SVG и .mmd. Проверьте, что файл открывается отдельно и соответствует изменённому описанию. Для собственного набора начните с замены одной сцены в исходном модуле, пересоберите проект и повторите проверку. Так проще отделить ошибку данных от ошибки интеграции.

node --version
npm.cmd ci --ignore-scripts
npm.cmd run build
npm.cmd test
npm.cmd start
# Если нужен другой свободный порт:
# $env:PORT = '8180'
# npm.cmd start

Linux: сборка, тесты и работа с готовой статикой

На Linux используется тот же проект. Установите подходящий Node.js способом, принятым в вашем окружении, и проверьте фактическую версию: пакет дистрибутива может быть старше требуемой. После npm ci сборка помещает готовые файлы в public, а тесты проверяют настоящий парсер библиотеки.

Для просмотра запустите локальный сервер либо другой HTTP-сервер статики. PHP или серверная база данных этой мастерской не нужны: описание преобразуется в браузере. Если вы встраиваете её в существующий PHP-сайт, удобнее оставить редактор отдельной страницей или iframe, чтобы стили и обработчики темы не мешали рабочей области.

Храните .mmd рядом с документом или исходниками проекта. Это позволит увидеть изменения схемы обычным текстовым сравнением. Однако текстовое ревью не заменяет просмотра результата: небольшое изменение связи может заметно перестроить раскладку. Перед публикацией документа проверьте изображение после последней сборки, а не старый сохранённый скриншот.

node --version
npm ci --ignore-scripts
npm run build
npm test
npm start
# Другой порт:
# PORT=8180 npm start

VPS: публикация public через Caddy или Nginx

Для готовой мастерской достаточно обычного веб-сервера. Соберите проект локально или в CI и перенесите public в отдельный каталог сайта. Node.js-процесс на VPS для показа схем не требуется. Настройте домен, HTTPS и права чтения файлов пользователю веб-сервера.

В Caddy это обычный file_server. При использовании Nginx проверьте подключение стандартных MIME-типов: JavaScript должен возвращаться с корректным Content-Type. Ошибка типа содержимого способна остановить модуль даже тогда, когда URL отвечает статусом 200. Относительные пути ресурсов позволяют разместить мастерскую в подкаталоге.

Не публикуйте node_modules, тестовые каталоги и секреты вместе со статикой. Ссылка на ZIP исходников должна указывать на реально доступный файл; при самостоятельном размещении измените её под свой раздел загрузок. После развёртывания откройте страницу по окончательному HTTPS-адресу, постройте схему и скачайте оба формата, проверяя уже серверную копию.

demo.example.com {
    root * /srv/mermaid-workshop/public
    encode zstd gzip
    file_server
}

# Проверка опубликованного ресурса:
# curl -I https://demo.example.com/assets/app.js

Проверки: парсер, SVG и пользовательский сценарий

Node-тесты проекта используют настоящий парсер Mermaid в окружении JSDOM. Они подтверждают, что поддерживаемые описания разбираются и ограничения ввода работают. Такая проверка полезна для CI, но она не строит доказательство хорошей геометрии SVG и не подтверждает мобильное удобство.

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

Проверяйте не только успешное изображение, но и отсутствие устаревшего результата после ошибки. Человек должен понимать, какой текст соответствует скачиваемому файлу. Для интерфейса важны видимый фокус, ясная ошибка, доступность кнопок и прокрутка большой схемы внутри области. Это отдельные свойства продукта, которые нельзя заменить одним успешным автоматическим тестом.

npm test
npm run build
# В браузере:
# 9 сцен → изменение текста → ошибка → исправление
# темы → масштаб → SVG → .mmd → узкий экран

Как использовать результат в своей работе и где читать дальше

Начните с процесса, который команда уже обсуждает словами: маршрут заявки, обмен API или переходы заказа. Выберите соответствующий тип диаграммы, оставьте только важные детали и попросите другого человека объяснить рисунок. Если он понимает связи иначе, уточните модель до реализации.

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

Архив содержит девять учебных сцен, HTML5-интерфейс, локальные зависимости, сборку, тесты и README для Windows/Linux/VPS. Собственные примеры распространяются по MIT; уведомления библиотек включены в проект. Официальная документация ниже поможет расширить синтаксис, однако новые возможности нужно проверять с закреплённой версией и выбранной политикой безопасности.

• Mermaid: возможности и типы диаграмм
• API: инициализация, parse и render
• Flowchart, sequence, state
• ER, Gantt, user journey
• Class diagram, GitGraph, mindmap
• Доступность диаграмм