Я неоднократно в заметках обозревал инструменты для ведения документации. Вот примеры продуктов:
▪ MkDocs - инструмент для генерации документации в виде статического сайта на базе текстовых файлов в формате markdown.
▪ BookStack - open source платформа для создания документации и вики-контента.
▪ Wiki.js - готовая wiki платформа с поддержкой редакторов wiki, markdown, wysiwyg.
Сегодня хочу рассказать про ещё один инструмент для автоматизации написания документации. А конкретно по её визуализации с помощью схем и диаграмм. Речь пойдёт про Mermaid. Это известный и популярный инструмент для создания визуализаций и диаграмм на основе написанного кода.
Основная идея Mermaid в том, что вы пишите текст, а на выходе получаете визуализацию. Это позволяет решать целый спектр задач, таких как:
1️⃣ Автоматизация создания контента.
2️⃣ Совместная работа с контентом.
3️⃣ Простая и понятная схема сохранения истории изменений.
Для понимания наглядный пример. Вот такой текст:
graph TD;
A-->B;
A-->C;
B-->D;
C-->D;
Превращается в картинку с блок схемой и стрелочками. Посмотрите остальные примеры на главной странице проекта, чтобы сразу понять, какой это инструмент и что с его помощью можно нарисовать.
С помощью Mermaid можно автоматизировать создание и изменение схем, редактируя текст после изменения структуры объектов. Автоматически будет меняться и картинка. История изменений отслеживается, всегда можно посмотреть прошлый вариант.
Самый простой и наглядный пример, где это может пригодиться - описание взаимодействия микросервисов, прохождение пользовательских запросов. Это как раз решается на уровне рисования блок-схем со стрелочками. Наглядные примеры с официального блога kubernetes.
На практике применение выглядит следующим образом. К примеру, github нативно поддерживает диаграммы Mermaid.js в README-файлах. Можно прямо в них писать код и он будет отрисовываться в картинки. Также Mermaid.js нативно интегрирована в GitLab, Gitea, Joplin и Notion. Для многих сервисов есть плагины. А в общем случае это пакет для nodejs, который можно поставить локально через nmp, запускать как сервис и обращаться к нему или с помощью CLI прогонять через него текстовые данные:
# npm install -g mermaid
# npm install -g @mermaid-js/mermaid-cli
# mmdc -i scheme.mmd -o scheme.png -w 1024 -H 768
Или с помощью Docker:
# docker run -it -v ~/diagrams:/data minlag/mermaid-cli \
-i /data/diagram.mmd
Попробовать Mermaid можно в онлайн редакторе https://mermaid.live. Итоговый результат можно кому-то отправить в виде ссылки.
Сайт - https://mermaid-js.github.io
Исходники - https://github.com/mermaid-js/mermaid
#docs
