Я неоднократно в заметках обозревал инструменты для ведения документации. Вот примеры продуктов:
▪️ MkDocs (https://t.me/srv_admin/2099) - инструмент для генерации документации в виде статического сайта на базе текстовых файлов в формате markdown.
▪️ BookStack (https://t.me/srv_admin/2096) - open source платформа для создания документации и вики-контента.
▪️ Wiki.js (https://t.me/srv_admin/561) - готовая wiki платформа с поддержкой редакторов wiki, markdown, wysiwyg.

Сегодня хочу рассказать про ещё один инструмент для автоматизации написания документации. А конкретно по её визуализации с помощью схем и диаграмм. Речь пойдёт про Mermaid. Это известный и популярный инструмент для создания визуализаций и диаграмм на основе написанного кода.

Основная идея Mermaid в том, что вы пишите текст, а на выходе получаете визуализацию. Это позволяет решать целый спектр задач, таких как:
1. Автоматизация создания контента.
2. Совместная работа с контентом.
3. Простая и понятная схема сохранения истории изменений.

Для понимания наглядный пример. Вот такой текст:

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

Превращается в картинку с блок схемой и стрелочками. Посмотрите остальные примеры на главной странице проекта (https://mermaid-js.github.io/), чтобы сразу понять, какой это инструмент и что с его помощью можно нарисовать.

С помощью Mermaid можно автоматизировать создание и изменение схем, редактируя текст после изменения структуры объектов. Автоматически будет меняться и картинка. История изменений отслеживается, всегда можно посмотреть прошлый вариант.

Самый простой и наглядный пример, где это может пригодиться - описание взаимодействия микросервисов, прохождение пользовательских запросов. Это как раз решается на уровне рисования блок-схем со стрелочками. Наглядные примеры (https://www.kubernetes.dev/blog/2021/12/01/improve-your-documentation-with-mermaid.js-diagrams/) с официального блога kubernetes.

На практике применение выглядит следующим образом. К примеру, github нативно поддерживает диаграммы Mermaid.js в README-файлах. Можно прямо в них писать код и он будет отрисовываться в картинки. Также Mermaid.js нативно интегрирована в GitLab, Gitea (https://t.me/srv_admin/1370), Joplin (https://t.me/srv_admin/1563) и 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