Диаграммы. Mermaid

Обновлено 2023-10-06 6 мин. для прочтения Computer-Science

Язык рисования диаграмм Mermaid.
Mermaid реализует концепцию Diagram as Code.

Содержание

1 Общая информация

Mermaid — язык программирования для рисования диаграмм и библиотека для визуализации.
Инструментарий написан на javascript.

1.1 Ресурсы

Страница Mermaid: https://mermaid-js.github.io/
Страница на github: https://github.com/mermaid-js/mermaid
Утилита командной строки: https://github.com/mermaid-js/mermaid-cli
HTTP сервер: https://github.com/TomWright/mermaid-server
Онлайн редактор: https://mermaid-js.github.io/mermaid-live-editor/

1.2 Интеграция

Интегрирован в системы рендеринга языка Markdown
- Pandoc: https://pandoc.org/
- Hugo: https://gohugo.io/
Хостинги кода (в файлах README.md)
- GitHub: https://github.com/
- GitLab: https://gitlab.com/
- Gitea: https://gitea.io/
Приложения работы с текстом (markdown)
- Joplin: https://joplinapp.org/
- Notion: https://www.notion.so/

1.3 Внедрение Mermaid в Markdown

Для блока кода, отмеченного как mermaid:
- система создаёт новый фрейм iframe,
- необработанный код из блока передаётся его в Mermaid.js,
- код преобразуется в диаграмму.

Пример входного кода

```mermaid
  graph TD;
      A-->B;
      A-->C;
      B-->D;
      C-->D;
```

Результирующее изображение
graph TD; A-->B; A-->C; B-->D; C-->D;

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

Блок-схемы (Flowchart)
Диаграммы состояния (Sequence diagram)
Диаграммы Ганта (Gantt diagram)
UML-диаграммы классов (Class diagram)
Графы git (Git graph)
ER-диаграммы (Entity Relationship Diagram)
Диаграммы пользовательского пути (User Journey Diagram)
Диаграммы последовательности (Sequence diagrams)
Круговые диаграммы (Pie chart)

1.5 Необходимое программное обеспечение

Необходимо установить программу mmdc из проекта https://github.com/mermaid-js/mermaid-cli.
```
yarn global add @mermaid-js/mermaid-cli
```

2 Синтаксис

%%: комментарий в коде.

3 Типы диаграмм

3.1 Блок-схемы (Flowchart)

Один из вариантов представления блок-схем.

3.1.1 Синтаксис

Ключевое слово: flowchart и аббревиатуры для указания направления.
subgraph <имя>: задаёт поддиаграммы.
- end: завершает описание поддиаграммы.
Основная часть диаграммы — это узлы.
- Текст на диаграмме узла берётся из названия.
- Альтернативно можно указать отображаемый текст в квадратных скобках.
- Форма узлов задаётся скобочными символами вокруг текста.
- Для экранирования используют кавычки.
  - Всё содержимое в кавычках считается текстом.
click: задаёт ссылку для узла.
```
click <узел> "<ссылка>" <_blank>
```
- Ссылка заключается в кавычки.
- _blank: указывает открыть ссылку в новой вкладке.
Направление диаграммы:
- TB: сверху вниз (top to bottom);
- TD: сверху вниз (top-down);
- BT: снизу вверх (bottom to top);
- RL: справа налево (right to left);
- LR: слева направо (left to right).
style: задаёт оформление диаграммы.
```
style <узел> <style_tag:значение>,<style_tag:значение>
```
- Теги стилей:
  - fill: заливка;
  - stroke: цвет границы;
  - stroke-width: толщина границы;
  - color: цвет текста;
  - stroke-dasharray: пунктирная граница.
- classDef: задаёт класс, содержащий набор стилей.
```
classDef <имя_класса> <style_tag:значение>,<style_tag:значение>
```
  - ::: указывает класс после имени узла.

3.1.2 Примеры

Блок
```
  flowchart TB
     node
```
flowchart TB node
Блок с текстом
```
  flowchart TB
     node[Текст]
```
flowchart TB node[Текст]

Формы узлов

  flowchart TB
    node1[Форма 1]
    node2(Форма 2)
    node3([Форма 3])
    node4[[Форма 4]]
    node5[(Форма 5)]
    node6((Форма 6))
    node7>Форма 7]
    node8{Форма 8}
    node9{{Форма 9}}
    node10[/Форма 10/]
    node11[\Форма 11\]
    node12[/Форма 12\]
    node13[\Форма 13/]

flowchart TB node1[Форма 1] node2(Форма 2) node3([Форма 3]) node4[[Форма 4]] node5[(Форма 5)] node6((Форма 6)) node7>Форма 7] node8{Форма 8} node9{{Форма 9}} node10[/Форма 10/] node11[\Форма 11\] node12[/Форма 12\] node13[\Форма 13/]

Стрелки

  flowchart TB
     А --> B
     C --- D
     E -.-> F
     G ==> H
     I --o J
     K --x L

flowchart TB А --> B C --- D E -.-> F G ==> H I --o J K --x L

Стрелки с текстом

  flowchart TD
      A -- Text --- B
      C --- |Text| D
      E --> |Text| F
      G -- Text --> H
      I -. Text .-> J
      K == Text ==> L

flowchart TD A -- Text --- B C --- |Text| D E --> |Text| F G -- Text --> H I -. Text .-> J K == Text ==> L

Поддиаграммы

  flowchart TB
      c1 --> a2
      subgraph one
          a1 --> a2
      end
      subgraph two
          b1 --> b2
      end
      subgraph three
          c1 --> c2
      end

flowchart TB c1 --> a2 subgraph one a1 --> a2 end subgraph two b1 --> b2 end subgraph three c1 --> c2 end

Ссылки

  flowchart TB
      A --> B
      click A "http://www.github.com" _blank

flowchart TB A --> B click A "http://www.github.com" _blank

Стили

  flowchart LR
      id1(Start)-->id2(Stop)
      style id1 fill:#3f3,stroke:#333,stroke-width:4px
      style id2 fill:#ff2400,stroke:#333,stroke-width:4px,color:#fff,stroke-dasharray: 12 5

flowchart LR id1(Start)-->id2(Stop) style id1 fill:#3f3,stroke:#333,stroke-width:4px style id2 fill:#ff2400,stroke:#333,stroke-width:4px,color:#fff,stroke-dasharray: 12 5

Классы стилей

  flowchart LR
      classDef class1 fill:#3f3,stroke:#333,stroke-width:4px
      classDef class2 fill:#ff2400,stroke:#333,stroke-width:4px,color:#fff,stroke-dasharray: 12 5

      A(Start):::class1 --> B(Stop):::class2

flowchart LR classDef class1 fill:#3f3,stroke:#333,stroke-width:4px classDef class2 fill:#ff2400,stroke:#333,stroke-width:4px,color:#fff,stroke-dasharray: 12 5 A(Start):::class1 --> B(Stop):::class2

3.2 Диаграммы состояния (Sequence diagram)

3.2.1 Синтаксис

3.2.2 Примеры

3.3 Диаграммы Ганта (Gantt diagram)

3.3.1 Синтаксис

3.3.2 Примеры

3.4 UML-диаграммы классов (Class diagram)

3.4.1 Синтаксис

3.4.2 Примеры

3.5 Графы git (Git graph)

Описание стратегии ветвления git.

3.5.1 Синтаксис

Ключевое слово: gitGraph.
options: задаёт параметры отображения.
commit: отображается кружочком с хешем.
- Хеш коммита генерится автоматически.
checkout <branch>: переключает на новую ветку.
merge <branch>: сливает ветки.

3.5.2 Примеры

Простое ветвление

  gitGraph:
  options
  {
      "nodeSpacing": 100,
      "nodeRadius": 10
  }
  end
  commit
  branch newbranch
  checkout newbranch
  commit
  commit
  checkout master
  commit
  commit
  merge newbranch

gitGraph: options { "nodeSpacing": 100, "nodeRadius": 10 } end commit branch newbranch checkout newbranch commit commit checkout master commit commit merge newbranch

3.6 ER-диаграммы (Entity Relationship Diagram)

3.6.1 Синтаксис

3.6.2 Примеры

3.7 Диаграммы пользовательского пути (User Journey Diagram)

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

3.7.1 Синтаксис

journey: начинает диаграмму.
title: название диаграммы.
section: раздел диаграммы.
- В каждом разделе указываются конкретные шаги с оценкой по десятибалльной шкале и закреплённое за действием лицо.
- : разделитель полей.

3.7.2 Примеры

Простая диаграмма пользовательского пути

  journey
      title Процесс написания статьи
      section Поиск / изучение
        Поиск информации: 5: Я
        Структурирование: 5: Я
      section Пишем
        Пишем черновик: 5: Я
        Готовим картинки: 4: Я
      section Редактируем
          Проверяем: 3: Я, Соавтор
          Финальные правки: 2: Я
      section Публикация
          Публикуем: 5: Я
          Радуемся: 8: Я, Соавтор

journey title Процесс написания статьи section Поиск / изучение Поиск информации: 5: Я Структурирование: 5: Я section Пишем Пишем черновик: 5: Я Готовим картинки: 4: Я section Редактируем Проверяем: 3: Я, Соавтор Финальные правки: 2: Я section Публикация Публикуем: 5: Я Радуемся: 8: Я, Соавтор

3.8 Диаграммы последовательности (Sequence diagrams)

3.8.1 Синтаксис

3.8.2 Примеры

3.9 Круговые диаграммы (Pie chart)

Показывает, какую часть от общего числа занимает отдельные части.

3.9.1 Синтаксис

Ключевое слово: pie.
Оператор title позволяет задать название диаграммы.
- title можно опустить, тогда диаграмма будет безымянной.
Строки с названиями элементов.
- Данные записываются построчно следующим образом:
  - название в кавычках;
  - разделитель в виде двоеточия;
  - положительное числовое значение (поддерживается до двух знаков после запятой).

3.9.2 Примеры

Домашние животные

  pie title Домашние животные
      "Собаки" : 386
      "Кошки" : 85
      "Хомячки" : 15

pie title Домашние животные "Собаки" : 386 "Кошки" : 85 "Хомячки" : 15

Links to this note

Programming