Диаграммы. Mermaid

2021-01-03 · 6 мин. для прочтения

Язык рисования диаграмм 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)

2 Установка

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

С помощью yarn:

yarn global add @mermaid-js/mermaid-cli

С помощью pnpn:

pnpm install -g @mermaid-js/mermaid-cli

3 Синтаксис

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

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

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

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

4.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:значение>
```
  - ::: указывает класс после имени узла.

4.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

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

4.2.1 Синтаксис

4.2.2 Примеры

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

4.3.1 Синтаксис

4.3.2 Примеры

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

4.4.1 Синтаксис

4.4.2 Примеры

4.5 Графы git (Git graph)

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

4.5.1 Синтаксис

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

4.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

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

4.6.1 Синтаксис

4.6.2 Примеры

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

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

4.7.1 Синтаксис

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

4.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: Я, Соавтор

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

4.8.1 Синтаксис

4.8.2 Примеры

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

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

4.9.1 Синтаксис

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

4.9.2 Примеры

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

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

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

Обновлено 2025-03-24

Programming

Authors

Дмитрий Сергеевич Кулябов

Профессор кафедры теории вероятностей и кибербезопасности

Мои научные интересы включают физику, администрирование Unix и сетей.

← Правила ISO для набора математики 2021-01-05

Emacs. Основы работы 2021-01-03 →