ServerAdmin.ru

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

#схемы

www.tgoop.com/srv_admin/2130

7.5K viewsedited  Aug 16, 2022 at 06:11

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

#схемы

BY ServerAdmin.ru