Полное руководство по диаграммам Mermaid.js

Что такое Mermaid.js?

Почему стоит использовать Mermaid.js?

• Контроль версий: диаграммы — это текстовые файлы, поэтому их можно отслеживать в Git вместе с кодом
• Быстрые обновления: измените несколько строк текста вместо перерисовки целых диаграмм
• Согласованность: Mermaid автоматически управляет раскладкой и стилями, обеспечивая единообразные диаграммы
• Не нужны инструменты дизайна: не требуется Visio, Lucidchart или другие дорогие инструменты
• Документация как код: храните диаграммы в том же репозитории, что и документацию
• Кроссплатформенность: работает в браузерах и Node.js и интегрируется со многими платформами
• Бесплатно и с открытым исходным кодом: без лицензионных затрат, активное сообщество
• Множество типов диаграмм: поддерживает блок-схемы, диаграммы последовательностей, диаграммы классов и др.

Поддерживаемые типы диаграмм

Mermaid поддерживает широкий набор типов диаграмм для различных задач документации:

flowchart TD
    A[Start] --> B{Decision}
    B -->|Yes| C[Process]
    B -->|No| D[Alternative]
    C --> E[End]
    D --> E

sequenceDiagram
    participant User
    participant API
    participant DB
    User->>API: Request data
    API->>DB: Query
    DB-->>API: Results
    API-->>User: Response

classDiagram
    class Animal {
        +String name
        +int age
        +makeSound()
    }
    class Dog {
        +bark()
    }
    Animal <|-- Dog

stateDiagram-v2
    [*] --> Idle
    Idle --> Loading: Start
    Loading --> Success: Complete
    Loading --> Error: Fail
    Success --> [*]
    Error --> Idle: Retry

erDiagram
    CUSTOMER ||--o{ ORDER : places
    ORDER ||--|{ LINE_ITEM : contains
    CUSTOMER {
        int id
        string name
        string email
    }

gantt
    title Project Timeline
    dateFormat YYYY-MM-DD
    section Phase 1
    Design :a1, 2024-01-01, 30d
    Development :a2, after a1, 45d

pie title Distribution
    "Category A" : 42
    "Category B" : 30
    "Category C" : 28

gitGraph
    commit
    branch develop
    checkout develop
    commit
    checkout main
    merge develop

Начало работы с Mermaid

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

• Сосредотачивайте диаграммы на одном концепте или рабочем процессе
• Используйте осмысленные метки, описывающие реальную бизнес-логику
• Разбивайте сложные диаграммы на более мелкие взаимосвязанные диаграммы
• Добавляйте комментарии с помощью %% для объяснения сложных разделов
• Используйте последовательные правила именования в диаграммах
• Тестируйте диаграммы в целевой среде перед финализацией
• При необходимости добавляйте подсказки направления (TD, LR) для управления компоновкой
• Используйте subgraph для группировки связанных узлов в блок-схемах
• Используйте параметры стиля умеренно, чтобы сохранить читаемость
• Храните исходники диаграмм под версионным контролем вместе с кодом

Типовые сценарии использования

Дополнительные ресурсы

• Официальная документация Mermaid
• Репозиторий Mermaid на GitHub
• Справочник синтаксиса Mermaid