Диаграммы

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

Введение в Mermaid

Mermaid — это инструмент для генерации диаграмм на основе текста, поддерживающий множество типов диаграмм:

Блок-схема (Flowchart)
Диаграмма последовательностей (Sequence Diagram)
Диаграмма Ганта (Gantt Chart)
Диаграмма классов (Class Diagram)
Диаграмма состояний (State Diagram)
Круговая диаграмма (Pie Chart)
Путь пользователя (User Journey)
Граф Git (Git Graph)

Базовый синтаксис

Блок-схема

markdown

```mermaid
flowchart TD
    A[Старт] --> B{Вход выполнен?}
    B -->|Да| C[Показать главную]
    B -->|Нет| D[Показать вход]
    C --> E[Конец]
    D --> F[Ввод пользователя]
    F --> G{Вход успешен?}
    G -->|Да| C
    G -->|Нет| H[Показать ошибку]
    H --> D


**Результат:**

```mermaid
flowchart TD
    A[Старт] --> B{Вход выполнен?}
    B -->|Да| C[Показать главную]
    B -->|Нет| D[Показать вход]
    C --> E[Конец]
    D --> F[Ввод пользователя]
    F --> G{Вход успешен?}
    G -->|Да| C
    G -->|Нет| H[Показать ошибку]
    H --> D

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

markdown

```mermaid
sequenceDiagram
    participant Пользователь
    participant Фронтенд
    participant Бэкенд
    participant БД
    
    Пользователь->>Фронтенд: Запрос входа
    Фронтенд->>Бэкенд: Проверка пользователя
    Бэкенд->>БД: Запрос данных пользователя
    БД-->>Бэкенд: Возврат информации
    Бэкенд-->>Фронтенд: Результат проверки
    Фронтенд-->>Пользователь: Ответ на вход


**Результат:**

```mermaid
sequenceDiagram
    participant Пользователь
    participant Фронтенд
    participant Бэкенд
    participant БД
    
    Пользователь->>Фронтенд: Запрос входа
    Фронтенд->>Бэкенд: Проверка пользователя
    Бэкенд->>БД: Запрос данных пользователя
    БД-->>Бэкенд: Возврат информации
    Бэкенд-->>Фронтенд: Результат проверки
    Фронтенд-->>Пользователь: Ответ на вход

Подробности блок-схем

Типы узлов

markdown

```mermaid
flowchart LR
    A[Прямоугольник]
    B(Скруглённый)
    C((Круг))
    D{Ромб}
    E[[Подпрограмма]]
    F[(База данных)]
    G>Метка]


**Результат:**

```mermaid
flowchart LR
    A[Прямоугольник]
    B(Скруглённый)
    C((Круг))
    D{Ромб}
    E[[Подпрограмма]]
    F[(База данных)]
    G>Метка]

Типы связей

markdown

```mermaid
flowchart TD
    A --> B
    C --- D
    E -.-> F
    G ==> H
    I --o J
    K --x L


**Результат:**

```mermaid
flowchart TD
    A --> B
    C --- D
    E -.-> F
    G ==> H
    I --o J
    K --x L

Управление направлением

markdown

<!-- Сверху вниз -->
```mermaid
flowchart TD
    A --> B

mermaid

flowchart BT
    A --> B

mermaid

flowchart LR
    A --> B

mermaid

flowchart RL
    A --> B


### Пример сложной блок-схемы

```markdown
```mermaid
flowchart TD
    Start([Начало проекта]) --> Analysis[Анализ требований]
    Analysis --> Design[Системное проектирование]
    Design --> Dev{Этап разработки}
    
    Dev --> Frontend[Фронтенд]
    Dev --> Backend[Бэкенд]
    Dev --> Database[Проектирование БД]
    
    Frontend --> FrontTest[Тест фронтенда]
    Backend --> BackTest[Тест бэкенда]
    Database --> DataTest[Тест БД]
    
    FrontTest --> Integration[Интеграционное тестирование]
    BackTest --> Integration
    DataTest --> Integration
    
    Integration --> Deploy{Подготовка к деплою}
    Deploy -->|Успех| Production[Продакшн]
    Deploy -->|Ошибка| Bug[Исправить ошибки]
    Bug --> Integration
    
    Production --> Monitor[Мониторинг]
    Monitor --> End([Завершение проекта])
    
    style Start fill:#e1f5fe
    style End fill:#e8f5e8
    style Bug fill:#ffebee


**Результат:**

```mermaid
flowchart TD
    Start([Начало проекта]) --> Analysis[Анализ требований]
    Analysis --> Design[Системное проектирование]
    Design --> Dev{Этап разработки}
    
    Dev --> Frontend[Фронтенд]
    Dev --> Backend[Бэкенд]
    Dev --> Database[Проектирование БД]
    
    Frontend --> FrontTest[Тест фронтенда]
    Backend --> BackTest[Тест бэкенда]
    Database --> DataTest[Тест БД]
    
    FrontTest --> Integration[Интеграционное тестирование]
    BackTest --> Integration
    DataTest --> Integration
    
    Integration --> Deploy{Подготовка к деплою}
    Deploy -->|Успех| Production[Продакшн]
    Deploy -->|Ошибка| Bug[Исправить ошибки]
    Bug --> Integration
    
    Production --> Monitor[Мониторинг]
    Monitor --> End([Завершение проекта])
    
    style Start fill:#e1f5fe
    style End fill:#e8f5e8
    style Bug fill:#ffebee

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

Базовый синтаксис

mermaid

sequenceDiagram
    Alice->>Bob: Привет, Боб, как дела?
    Bob-->>Alice: Всё хорошо, спасибо!
    Alice-)Bob: Пока!

Результат:

mermaid

sequenceDiagram
    Alice->>Bob: Привет, Боб, как дела?
    Bob-->>Alice: Всё хорошо, спасибо!
    Alice-)Bob: Пока!

Полосы активности и жизненные линии

mermaid

sequenceDiagram
    participant A as Клиент
    participant B as Сервер
    
    A->>+B: Запрос данных
    Note right of B: Обработка запроса
    B-->>-A: Возврат данных
    
    A->>+B: Новый запрос
    B->>+B: Внутренняя обработка
    B-->>-B: Обработка завершена
    B-->>-A: Возврат результата

Результат:

mermaid

sequenceDiagram
    participant A as Клиент
    participant B as Сервер
    
    A->>+B: Запрос данных
    Note right of B: Обработка запроса
    B-->>-A: Возврат данных
    
    A->>+B: Новый запрос
    B->>+B: Внутренняя обработка
    B-->>-B: Обработка завершена
    B-->>-A: Возврат результата

Циклы и условия

mermaid

sequenceDiagram
    participant U as Пользователь
    participant S as Система
    
    U->>S: Запрос входа
    
    alt Имя пользователя найдено
        S->>S: Проверка пароля
        alt Пароль верный
            S-->>U: Вход успешен
        else Пароль неверный
            S-->>U: Неверный пароль
        end
    else Имя пользователя не найдено
        S-->>U: Пользователь не найден
    end
    
    opt Запомнить меня
        S->>S: Сохранить состояние входа
    end

Результат:

mermaid

sequenceDiagram
    participant U as Пользователь
    participant S as Система
    
    U->>S: Запрос входа
    
    alt Имя пользователя найдено
        S->>S: Проверка пароля
        alt Пароль верный
            S-->>U: Вход успешен
        else Пароль неверный
            S-->>U: Неверный пароль
        end
    else Имя пользователя не найдено
        S-->>U: Пользователь не найден
    end
    
    opt Запомнить меня
        S->>S: Сохранить состояние входа
    end

Диаграмма классов

mermaid

classDiagram
    class Animal {
        +String name
        +int age
        +eat()
        +sleep()
    }
    
    class Dog {
        +String breed
        +bark()
        +wagTail()
    }
    
    class Cat {
        +String color
        +meow()
        +purr()
    }
    
    Animal <|-- Dog
    Animal <|-- Cat
    
    class Owner {
        +String name
        +feedPet()
    }
    
    Owner --> Animal : владеет

Результат:

mermaid

classDiagram
    class Animal {
        +String name
        +int age
        +eat()
        +sleep()
    }
    
    class Dog {
        +String breed
        +bark()
        +wagTail()
    }
    
    class Cat {
        +String color
        +meow()
        +purr()
    }
    
    Animal <|-- Dog
    Animal <|-- Cat
    
    class Owner {
        +String name
        +feedPet()
    }
    
    Owner --> Animal : владеет

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

mermaid

stateDiagram-v2
    [*] --> Ожидание
    Ожидание --> Выполнение : Старт
    Выполнение --> Пауза : Пауза
    Выполнение --> Завершено : Конец
    Пауза --> Выполнение : Возобновить
    Пауза --> Остановлено : Стоп
    Остановлено --> Ожидание : Сброс
    Завершено --> Ожидание : Сброс
    Завершено --> [*]
    
    state Выполнение {
        [*] --> Инициализация
        Инициализация --> Обработка
        Обработка --> Проверка
        Проверка --> [*]
    }

Результат:

mermaid

stateDiagram-v2
    [*] --> Ожидание
    Ожидание --> Выполнение : Старт
    Выполнение --> Пауза : Пауза
    Выполнение --> Завершено : Конец
    Пауза --> Выполнение : Возобновить
    Пауза --> Остановлено : Стоп
    Остановлено --> Ожидание : Сброс
    Завершено --> Ожидание : Сброс
    Завершено --> [*]
    
    state Выполнение {
        [*] --> Инициализация
        Инициализация --> Обработка
        Обработка --> Проверка
        Проверка --> [*]
    }

Диаграмма Ганта

mermaid

gantt
    title График разработки проекта
    dateFormat  YYYY-MM-DD
    section Анализ требований
    Сбор требований          :done,    des1, 2024-01-01,2024-01-05
    Анализ требований        :done,    des2, after des1, 5d
    Проверка требований      :done,    des3, after des2, 2d
    
    section Проектирование
    Системное проектирование :active,  design1, 2024-01-12, 7d
    Дизайн интерфейса        :         design2, after design1, 5d
    Проектирование БД        :         design3, after design1, 3d
    
    section Разработка
    Фронтенд                 :         dev1, after design2, 10d
    Бэкенд                   :         dev2, after design3, 12d
    Тестирование             :         test1, after dev1, 5d

Круговая диаграмма

mermaid

pie title Источники трафика сайта
    "Поисковые системы" : 45
    "Социальные сети" : 25
    "Прямые переходы" : 20
    "Email-маркетинг" : 7
    "Другое" : 3

Путь пользователя

mermaid

journey
    title Путь пользователя в интернет-магазине
    section Ознакомление
      Посещение главной: 3: Пользователь
      Просмотр товаров: 4: Пользователь
      Поиск товаров: 4: Пользователь
    section Рассмотрение
      Просмотр деталей: 4: Пользователь
      Сравнение цен: 3: Пользователь
      Чтение отзывов: 5: Пользователь
    section Покупка
      Добавить в корзину: 4: Пользователь
      Оформить заказ: 3: Пользователь
      Оплата: 2: Пользователь
    section Использование
      Получить товар: 5: Пользователь
      Использовать товар: 4: Пользователь
      Оставить отзыв: 4: Пользователь

Граф Git

mermaid

gitgraph
    commit id: "Первый коммит"
    commit id: "Добавлен модуль пользователя"
    branch feature/auth
    commit id: "Добавлен вход"
    commit id: "Добавлена регистрация"
    checkout main
    commit id: "Исправлена ошибка на главной"
    merge feature/auth
    commit id: "v1.0 релиз"
    branch hotfix
    commit id: "Срочное исправление"
    checkout main
    merge hotfix
    commit id: "v1.0.1 релиз"

Примеры из практики

Диаграмма архитектуры системы

mermaid

flowchart TB
    subgraph "Пользовательский уровень"
        Web[Веб-браузер]
        Mobile[Мобильное приложение]
        API[API-клиент]
    end
    
    subgraph "Уровень шлюза"
        Gateway[API-шлюз]
        Auth[Сервис аутентификации]
    end
    
    subgraph "Сервисный уровень"
        UserService[Сервис пользователей]
        OrderService[Сервис заказов]
        PaymentService[Сервис платежей]
        NotificationService[Сервис уведомлений]
    end
    
    subgraph "Уровень данных"
        UserDB[(БД пользователей)]
        OrderDB[(БД заказов)]
        Cache[(Redis Cache)]
        Queue[Очередь сообщений]
    end
    
    Web --> Gateway
    Mobile --> Gateway
    API --> Gateway
    
    Gateway --> Auth
    Gateway --> UserService
    Gateway --> OrderService
    Gateway --> PaymentService
    
    UserService --> UserDB
    OrderService --> OrderDB
    PaymentService --> Queue
    NotificationService --> Queue
    
    UserService --> Cache
    OrderService --> Cache
    
    style Gateway fill:#e1f5fe
    style Auth fill:#fff3e0
    style Cache fill:#f3e5f5

Сценарий вызова API

mermaid

sequenceDiagram
    participant C as Клиент
    participant G as API-шлюз
    participant A as Сервис аутентификации
    participant U as Сервис пользователей
    participant D as БД
    participant R as Redis
    
    C->>G: Запрос информации о пользователе
    G->>A: Проверка токена
    A->>R: Проверка токена в кэше
    R-->>A: Токен валиден
    A-->>G: Аутентификация успешна
    
    G->>U: Получить данные пользователя
    U->>R: Проверка пользователя в кэше
    alt Кэш найден
        R-->>U: Вернуть данные пользователя
    else Кэш не найден
        U->>D: Запрос к базе данных
        D-->>U: Вернуть информацию
        U->>R: Обновить кэш
    end
    
    U-->>G: Вернуть данные пользователя
    G-->>C: Ответ пользователю

Бизнес-процесс заказа

mermaid

flowchart TD
    Start([Заказ пользователя]) --> Check{Проверить наличие}
    Check -->|В наличии| Reserve[Зарезервировать]
    Check -->|Нет в наличии| OutOfStock[Нет на складе]
    OutOfStock --> Notify[Уведомить пользователя]
    Notify --> End1([Конец])
    
    Reserve --> Payment{Оплата}
    Payment -->|Успех| ConfirmOrder[Подтвердить заказ]
    Payment -->|Ошибка| ReleaseStock[Освободить резерв]
    ReleaseStock --> PaymentFailed[Ошибка оплаты]
    PaymentFailed --> End2([Конец])
    
    ConfirmOrder --> UpdateInventory[Обновить склад]
    UpdateInventory --> SendNotification[Отправить уведомление]
    SendNotification --> Logistics[Организовать доставку]
    Logistics --> End3([Заказ завершён])
    
    style Start fill:#e8f5e8
    style End1 fill:#ffebee
    style End2 fill:#ffebee
    style End3 fill:#e8f5e8
    style OutOfStock fill:#ffebee
    style PaymentFailed fill:#ffebee

Стили и темы

Стили узлов

mermaid

flowchart LR
    A[Стиль по умолчанию] --> B[Стиль 1]
    A --> C[Стиль 2]
    A --> D[Стиль 3]
    
    style B fill:#f9f,stroke:#333,stroke-width:4px
    style C fill:#bbf,stroke:#f66,stroke-width:2px,color:#fff,stroke-dasharray: 5 5
    style D fill:#f96,stroke:#333,stroke-width:4px,color:#fff

Стили классов

mermaid

flowchart LR
    A[Узел A]:::classA --> B[Узел B]:::classB
    A --> C[Узел C]:::classC
    
    classDef classA fill:#e1f5fe,stroke:#01579b,stroke-width:2px
    classDef classB fill:#f3e5f5,stroke:#4a148c,stroke-width:2px
    classDef classC fill:#e8f5e8,stroke:#1b5e20,stroke-width:2px

Конфигурация и совместимость

Конфигурация VitePress

javascript

// .vitepress/config.js
export default {
  markdown: {
    mermaid: true
  }
}

Поддержка на GitHub

GitHub нативно поддерживает Mermaid, вы можете использовать его прямо в Markdown-файлах:

markdown

```mermaid
graph LR
    A --> B


### Поддержка других платформ

| Платформа      | Поддержка    | Требования к настройке |
|---------------|--------------|-----------------------|
| **GitHub**    | ✅ Встроено   | Нет                   |
| **GitLab**    | ✅ Встроено   | Нет                   |
| **VitePress** | ✅ Плагин     | Требует настройки     |
| **Jekyll**    | ✅ Плагин     | Установить плагин     |
| **Hugo**      | ✅ Тема       | Зависит от темы       |

## Лучшие практики

### Советы по оформлению

```markdown
✅ Рекомендуется:

1. **Делайте просто:**
   - Не усложняйте диаграммы
   - Используйте понятные подписи и связи

2. **Логичная структура:**
   - Выбирайте подходящее направление
   - Сохраняйте логичность потока

3. **Единый стиль:**
   - Используйте единую цветовую схему
   - Сохраняйте стиль диаграмм

4. **Добавляйте пояснения:**
   - Для сложных диаграмм добавляйте заголовки
   - Поясняйте текстом при необходимости

❌ Избегайте:

1. Диаграмм, которые сложно понять
2. Слишком много пересечений линий
3. Неясных подписей
4. Отсутствия легенды

Производительность

markdown

- **Оптимизация больших диаграмм:**
  - Разбивайте сложные диаграммы
  - Используйте подграфы для организации

- **Производительность загрузки:**
  - Не размещайте слишком много диаграмм на одной странице
  - Используйте ленивую загрузку

- **Адаптация под мобильные:**
  - Убедитесь, что диаграммы читаемы на маленьких экранах
  - Используйте горизонтальную прокрутку при необходимости

Связанный синтаксис

Встраивание HTML — расширения HTML
Математические формулы — выражения LaTeX
Лучшие практики — советы по написанию

Инструменты и ресурсы

Онлайн-редакторы

Mermaid Live Editor: Официальный онлайн-редактор
Draw.io: Универсальный инструмент для диаграмм
Lucidchart: Профессиональная платформа для диаграмм
Excalidraw: Диаграммы в стиле от руки

Инструменты для разработчиков

Mermaid CLI: Командная строка
VS Code Mermaid: Расширение для Visual Studio Code
Atom Mermaid: Плагин для Atom
IntelliJ Mermaid: Плагин для JetBrains IDE

Справочные материалы

Официальная документация Mermaid: Полный синтаксис
Библиотека примеров Mermaid: Примеры диаграмм
GitHub Mermaid: Использование на GitHub
Awesome Mermaid: Сборник ресурсов

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

Диаграммы ​

Введение в Mermaid ​

Базовый синтаксис ​

Блок-схема ​

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

Подробности блок-схем ​

Типы узлов ​

Типы связей ​

Управление направлением ​

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

Базовый синтаксис ​

Полосы активности и жизненные линии ​

Циклы и условия ​

Диаграмма классов ​

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

Диаграмма Ганта ​

Круговая диаграмма ​

Путь пользователя ​

Граф Git ​

Примеры из практики ​

Диаграмма архитектуры системы ​

Сценарий вызова API ​

Бизнес-процесс заказа ​

Стили и темы ​

Стили узлов ​

Стили классов ​

Конфигурация и совместимость ​

Конфигурация VitePress ​

Поддержка на GitHub ​

Производительность ​

Связанный синтаксис ​

Инструменты и ресурсы ​

Онлайн-редакторы ​

Инструменты для разработчиков ​

Справочные материалы ​

Диаграммы

Введение в Mermaid

Базовый синтаксис

Блок-схема

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

Подробности блок-схем

Типы узлов

Типы связей

Управление направлением

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

Базовый синтаксис

Полосы активности и жизненные линии

Циклы и условия

Диаграмма классов

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

Диаграмма Ганта

Круговая диаграмма

Путь пользователя

Граф Git

Примеры из практики

Диаграмма архитектуры системы

Сценарий вызова API

Бизнес-процесс заказа

Стили и темы

Стили узлов

Стили классов

Конфигурация и совместимость

Конфигурация VitePress

Поддержка на GitHub

Производительность

Связанный синтаксис

Инструменты и ресурсы

Онлайн-редакторы

Инструменты для разработчиков

Справочные материалы