Документирование в целом требует работы с некоторыми видами диаграмм, будь то архитектура приложений, изображения потоков пользователей или любые представления отчетов, такие как круговые диаграммы и диаграммы Ганта.
Ранее механизм заключался в том, чтобы включать диаграммы в виде изображений после их создания в таких инструментах, как draw.io и подобных. Самый большой недостаток этого механизма заключается в том, что рабочий процесс изменения любой из созданных диаграмм очень сложен. Это приводит к отсутствию заинтересованности в поддержании диаграмм в актуальном состоянии, что еще больше приводит к пробелам в общей согласованности документации.
Вот тут-то и появляется Mermaid. Верный своему красивому названию, Mermaid делает процесс создания красивых диаграмм и диаграмм и их дальнейших модификаций очень простым. Слово `modifying` становится здесь ключевым, так как это та область, за которой мы, как разработчики, изо всех сил пытаемся идти в ногу.
Как и `Infrastructure As Code or IAC`, я бы сказал, что это `Diagram As Code or DAC`. Mermaid позволяет декларативно создавать диаграммы в синтаксисе, подобном Markdown. Детали находятся в виде простого текста и могут быть легко изменены в любой момент времени, а также довольно легко переданы и включены в документацию.
Чтобы начать их создавать, мы можем работать с любым `editor` по выбору, скажем, VS Code или Sublime Text или VIM с установленными соответствующими пакетами плагинов `mermaid`.
Mermaid поставляется с интеграциями для многих из них. Подробнее вы можете узнать на странице здесь — Mermaid — Интеграции
Я буду работать с VS Code. Если вы тоже это сделаете, установите это расширение `Markdown Preview Mermaid Support`, и все будет готово.
Давайте рассмотрим несколько простых примеров:
Создайте new file в VS Code и выберите language` как Markdown`.
Создадим схему:
В созданный вами файл введите приведенный ниже код (как есть, включая галочки)
```mermaid graph TD; A --> B ```
Теперь откройте вкладку Preview, и вы должны увидеть простой график с двумя узлами, соединяющими точки A и B, например:
Вот оно! Вы создали свою первую диаграмму, используя только текстовые объявления!
graph — определяет тип диаграммы, которую вы хотите создать.
`TD` указывает на график `Top Down`. Это можно изменить на то, что вы считаете нужным, например `LR for Left Right`, как показано ниже.
```mermaid graph LR; A --> B ```
Должно дать что-то вроде этого:
Давайте теперь придадим некоторую форму нашим узлам.
```mermaid
graph LR;
1[A] --> 2{B}
```
Скобки square вокруг узла дают форму `rectangle`, а фигурные скобки `curly` дают форму `diamond`. При указании узлов с фигурами вам также необходимо указать `identifier`, который в данном случае является просто `name` для таких узлов, как `1` и `2`. Это может быть что угодно `alphanumeric`
Формы узлов, типы стрелок (сплошные, пунктирные и т.д.), метки для стрелок и многое другое можно довольно эффективно создать с помощью `Mermaid`. За всеми подробностями вы можете обратиться сюда — Русалка — Синтаксис диаграммы
Мы можем расширить график, чтобы обозначить какой-то поток, блок-схему за просмотр.
Ниже я пытаюсь изобразить простой User login flow :
```mermaid
graph TD
a((User)) --> b[[Login]]
b --> c{Has <br>account?} --> |Yes| d{Credentials Valid?} --> |No| b
c -->|No| e[[Sign Up]] --> b
d -->|Yes| f([Login successful])
```
Вы должны увидеть что-то вроде этого:
Как видите, вся блок-схема представлена в простом текстовом формате. Вот откуда приходит сила.
Mermaid можно использовать не только для блок-схем, но и для создания более сложных диаграмм.
Вот пример простого Pie chart:
Все, что вам нужно сделать, это указать `title` для диаграммы вместе с `label` и `value` для отдельных частей круговой диаграммы.
```mermaid pie title Incident Distribution by Priority “Priority 2”: 5 “Priority 3”: 10 “Priority 4”: 15 ```
И вы должны получить что-то вроде этого на панели preview:
Разве это не прекрасно и просто?
`Sequence Diagram` - это то, с чем мы очень часто сталкиваемся, и его также довольно просто создать в `Mermaid`.
Вот один пример, изображающий последовательность взаимодействий между двумя людьми в кофейне.
```mermaid sequenceDiagram Shyam ->> +Maya: Hello Maya, how are you? Shyam ->> +Maya: Maya, can you hear me? Maya ->> +CoffeeDay: One Latte for me Maya ->> -Shyam: Hi Shyam, I can hear you! Maya ->> -Shyam: I feel great! Shyam ->> CoffeeDay: One for me too! ```
Дает вам эту красивую диаграмму:
Все это из простых данных уценки. Это действительно потрясающе!
Mermaid очень мощная программа, и это отличный способ включить диаграммы в любую документацию. Время цикла для внесения изменений и их отражения очень короткое, и в этом заключается вариант использования. Попробуй.
Приятного изучения. До следующего раза, адиос!
