​​Я неоднократно в заметках обозревал инструменты для ведения документации. Вот примеры продуктов: ▪ 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