Диаграммы Mermaid

Mermaid — это текстовый язык для схем: блок-схемы, последовательности вызовов, простые диаграммы состояний и т.д. В документации проекта диаграммы не рисуются картинкой, а описываются кодом в Markdown — при сборке сайта VitePress их превращает в графику.

Подключение уже настроено (vitepress-plugin-mermaid, Mermaid 11). Вам достаточно добавить блок в .md файл.

Как вставить диаграмму

1. Откройте нужный Markdown-файл.
2. Вставьте fenced-блок с подсветкой mermaid (три обратные кавычки, слово mermaid, новая строка, код диаграммы, снова три кавычки).

Альтернатива: язык блока mmd — плагин обрабатывает его так же, как mermaid.

Светлая и тёмная темы сайта подхватываются автоматически.

Минимальный пример (блок-схема)

Как писать в Markdown:

```mermaid
flowchart LR
  A[Начало] --> B{Есть данные?}
  B -->|да| C[Обработка]
  B -->|нет| D[Ошибка]
  C --> E[Конец]
  D --> E
```

Как это выглядит на сайте:

Направление: TB — сверху вниз, LR — слева направо, RL — справа налево.

Диаграмма последовательности

Удобно для сценариев «кто кого вызывает» (API, очереди, плагины).

```mermaid
sequenceDiagram
  participant П as Пользователь
  participant С as Сайт
  participant А as API
  П->>С: Открывает форму
  С->>А: Запрос данных
  А-->>С: JSON
  С-->>П: Страница с данными
```

Подграфы (группы в блок-схеме)

Удобно для этапов «установка / настройка / эксплуатация»:

```mermaid
flowchart TB
  subgraph Установка
    A[Скачать пакет] --> B[Установить через установщик]
  end
  subgraph Настройка
    B --> C[Системные настройки]
    C --> D[Права доступа]
  end
```

Диаграмма состояний

Подходит для жизненного цикла заказа, статуса задачи и т.п.:

```mermaid
stateDiagram-v2
  [*] --> Черновик
  Черновик --> Опубликован: публикация
  Опубликован --> Архив: снятие с витрины
  Архив --> [*]
```

Круговая диаграмма (pie)

Доли в процентах, подписи через двоеточие:

```mermaid
pie title Источники трафика (пример)
  "Поиск" : 45
  "Прямые" : 30
  "Соцсети" : 25
```

Простая диаграмма классов

Когда нужно показать сущности и связи без UML в полный рост:

```mermaid
classDiagram
  class Заказ {
    +int id
    +float total
  }
  class Позиция {
    +int count
  }
  Заказ "1" --> "*" Позиция : содержит
```

Советы

• Синтаксис и все типы диаграмм — в официальной документации Mermaid. Там же: ER, Git graph, journey и др.
• Если диаграмма не отображается, проверьте отступы, закрытие блока тремя кавычками и отсутствие опечаток в ключевых словах (flowchart, sequenceDiagram и т.д.).
• Для сложных схем лучше разбить на две простые страницы или две диаграммы — так проще читать и править.
• Подписи на кириллице обычно работают; при странном отображении попробуйте упростить текст в узлах или взять короткие id в participant X as Подпись.

См. также раздел «Диаграммы Mermaid» в возможностях VitePress.