Рисование диаграмм в Markdown

Диаграммы очень важны в технической документации; они могут помочь нам:

  • Визуализируйте сложные взаимосвязи данных
  • Отображайте архитектуру системы и рабочие процессы
  • Выражайте идеи и концепции более ясно

Популярные инструменты для построения диаграмм в Markdown

Mermaid

Mermaid — один из самых популярных инструментов для создания диаграмм в Markdown. Он позволяет создавать различные диаграммы с помощью простого текстового синтаксиса.

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

  • Блок-схема
  • Диаграмма последовательности
  • Диаграмма классов
  • Диаграмма состояний
  • Диаграмма Ганта
  • Круговая диаграмма

Блок-схема

```mermaid
graph TD
    A[开始] --> B{条件判断}
    B -->|Yes| C[执行操作A]
    B -->|No| D[执行操作B]
    C --> E[结束]
    D --> E
```

Направление блок-схемы

  • TDилиTB: Сверху вниз
  • BT: Снизу вверх
  • RL: Справа налево
  • LR: Слева направо

Фигуры узлов

  • A[方形]: Прямоугольник
  • B(圆角矩形): Скруглённый прямоугольник
  • C{菱形}: Ромб (решение)
  • D((圆形)): Круг
  • E>旗帜形]: Фигура флажка

Типы соединительных линий

  • -->Сплошная стрелка
  • -.->Пунктирная стрелка
  • ==>Толстая сплошная стрелка
  • --Сплошная линия
  • -.Пунктирная линия

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

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

```mermaid
sequenceDiagram
    participant A as 用户
    participant B as 系统
    participant C as 数据库
    
    A->>B: 登录请求
    B->>C: 验证用户信息
    C-->>B: 返回验证结果
    B-->>A: 登录成功/失败
```

Основы синтаксиса диаграммы последовательности:

  • participantОпределить участников
  • ->>Сплошная стрелка
  • -->>Пунктирная стрелка
  • noteДобавить заметки

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

```mermaid
gantt
    title 项目开发计划
    dateFormat  YYYY-MM-DD
    section 设计阶段
    需求分析      :done,    des1, 2024-01-01,2024-01-15
    UI设计       :active,  des2, 2024-01-10, 30d
    section 开发阶段
    前端开发      :         dev1, after des2, 45d
    后端开发      :         dev2, 2024-02-01, 60d
    section 测试阶段
    单元测试      :         test1, after dev1, 15d
    集成测试      :         test2, after dev2, 10d
```

Основы синтаксиса диаграммы Ганта:

  • titleУстановить заголовок
  • dateFormatОпределить формат даты
  • sectionОпределить фазы
  • Статус задачи:done(Завершено),active(В процессе),crit(Критично)

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

```mermaid
pie
    title 浏览器市场份额
    "Chrome" : 65
    "Safari" : 15
    "Firefox" : 10
    "其他" : 10
```

Подробные типы диаграмм

Блок-схема

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

Пример Mermaid:

```mermaid
graph LR
    A[开始] --> B{条件判断}
    B -->|是| C[执行操作1]
    B -->|否| D[执行操作2]
    C --> E[结束]
    D --> E
```

Объяснение синтаксиса:

  • graphОбъявление блок-схемы
  • LRУказывает расположение слева направо (необязательно TB/RL/BT)
  • -->Указывает соединение стрелкой
  • []Указывает прямоугольный узел
  • {}Обозначает ромбовидный узел условия

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

Диаграмма последовательности показывает порядок взаимодействия между объектами.

Пример Mermaid:

```mermaid
sequenceDiagram
    participant 用户
    participant 系统
    用户->>系统: 登录请求
    系统-->>用户: 验证请求
    用户->>系统: 提交凭证
    系统-->>用户: 登录成功
```

Объяснение синтаксиса:

  • participantОпределить участников
  • ->>Обозначает сплошную стрелку
  • -->>Обозначает пунктирную стрелку

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

Диаграмма классов используется для объектно-ориентированного проектирования и показывает классы и их отношения.

```mermaid
classDiagram
    class 用户 {
        +用户名: string
        +密码: string
        +登录()
    }
    
    class 订单 {
        +订单号: int
        +创建日期: date
        +计算总价()
    }
    
    用户 "1" --> "n" 订单
```

Дополнительные советы

1. Настройка темы

Mermaid позволяет настраивать стили диаграмм:

```mermaid
%%{init: {'theme': 'forest'}}%%
pie
    title 自定义主题
    "项目A" : 30
    "项目B" : 50
    "项目C" : 20
```

2. Интерактивные диаграммы

Некоторые инструменты поддерживают добавление интерактивных функций:

```mermaid
graph TD
    A[点击我] --> B[显示详细信息]
    click A "https://www.example.com" "这是提示文本"
```

3. Экспорт диаграмм

Большинство инструментов поддерживают экспорт диаграмм в формате:

  • PNG-изображения
  • Векторная графика SVG
  • Документы PDF

Статус поддержки инструментов

Инструмент/Платформа Mermaid PlantUML Graphviz
GitHub ✔ ✖ ✖
GitLab ✔ ✔ ✔
VS Code Плагин Плагин Плагин
Typora ✔ ✖ ✖
Obsidian Плагин Плагин Плагин

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

  1. Стремитесь к простоте: Диаграммы должны быть простыми и понятными, избегайте излишней детализации
  2. Единообразный стиль: Диаграммы в одном документе должны иметь единообразный стиль
  3. Добавляйте пояснения: Добавляйте текстовые пояснения для сложных диаграмм
  4. Управление версиями: текстовые диаграммы хорошо работают с Git
  5. Тестирование рендеринга: проверьте отображение диаграмм на разных платформах

ЧАВО

Вопрос 1: Почему моя диаграмма не отображается?

  • Проверьте, используете ли вы правильный синтаксис
  • Убедитесь, что ваш редактор Markdown/платформа поддерживает инструмент для диаграмм
  • Проверьте наличие синтаксических ошибок

Вопрос 2: Как изучить эти синтаксисы диаграмм?

Вопрос 3: Есть ли визуальный редактор?

Другие расширения