beautiful-mermaid: Скилл для генерации диаграмм

--- name: beautiful-mermaid description: Skill for using the beautiful-mermaid TypeScript library to render Mermaid diagrams to SVG or ASCII/Unicode, apply themes (including Shiki), and integrate in Node or browser contexts. --- # Beautiful Mermaid ## Overview Позволяет быстро и гибко создавать Mermaid-диаграммы в Node.js, браузере или CLI, используя пакет `beautiful-mermaid`. Используйте этот инструмент для генерации SVG-диаграмм, диаграмм в формате ASCII/Unicode и обеспечения согласованного оформления. ## Когда использовать - Рендеринг Mermaid-диаграмм в SVG или ASCII/Unicode. - Добавление или настройка тем оформления (двухцветная базовая тема, дополнительные цвета или темы Shiki). - Интеграция `beautiful-mermaid` в Node.js, браузер или инструменты командной строки. - Устранение неполадок при рендеринге диаграмм, отступов или оформления. ## Сценарии использования (примеры) - Вывод диаграмм в терминал/CLI: Используйте `renderMermaidAscii()` с `useAscii: true` для чистого ASCII. - Более красивый вывод в терминале: Используйте `renderMermaidAscii()` с кодировкой Unicode для отображения блоков. - Веб-страницы/компоненты React: Используйте `renderMermaid()` для получения SVG и встраивайте его в DOM. - Необходимость согласованного оформления: Используйте `THEMES['...']` для применения встроенной темы. - Необходимость использования фирменных цветов компании: Укажите `bg` + `fg` (монохромная тема) или добавьте `accent/muted/surface`. - Необходимость соответствия теме VS Code: Используйте Shiki + `fromShikiTheme()`. - Использование в CDN/без сборки: Используйте глобальный пакет для браузера через тег `<script>`. - Необходимость динамической смены темы: Обновляйте CSS-переменные SVG (`--bg`, `--fg`) без повторной отрисовки. ## Примеры использования (для разных групп пользователей) ### Разработчики/Инженеры - Вывод диаграмм в CLI/терминале: Используйте `renderMermaidAscii()` + совместимость с ASCII ```ts import { renderMermaidAscii } from 'beautiful-mermaid' const ascii = renderMermaidAscii('graph LR; A-->B', { useAscii: true }) ``` - Встраивание SVG в Web/React: Используйте `renderMermaid()` для генерации SVG-строки ```ts import { renderMermaid } from 'beautiful-mermaid' const svg = await renderMermaid('graph TD; A-->B') ``` - CI/генерация документации: Пакетная отрисовка SVG-файлов ```ts import { renderMermaid } from 'beautiful-mermaid' const svg = await renderMermaid('sequenceDiagramnA->>B: ping') ``` - Обеспечение единого стиля: Используйте встроенную тему или настройте цвета ```ts import { renderMermaid, THEMES } from 'beautiful-mermaid' const svg = await renderMermaid('graph TD; A-->B', THEMES['tokyo-night']) ``` ### Нетехнические пользователи - Экспорт SVG для встраивания в документацию: ```ts import { renderMermaid } from 'beautiful-mermaid' const svg = await renderMermaid('graph TD; A-->B') ``` - Обеспечение единого стиля на совещаниях/презентациях: Используйте фирменные цвета ```ts import { renderMermaid } from 'beautiful-mermaid' const svg = await renderMermaid('graph TD; A-->B', { bg: '#0f0f0f', fg: '#e0e0e0' }) ``` - Демонстрация ASCII/Unicode в терминале: ```ts import { renderMermaidAscii } from 'beautiful-mermaid' const unicode = renderMermaidAscii('graph LR; A-->B') ``` - Обеспечение согласованности дизайна: Используйте темы Shiki для соответствия стилю редактора ```ts import { getSingletonHighlighter } from 'shiki' import { renderMermaid, fromShikiTheme } from 'beautiful-mermaid' const highlighter = await getSingletonHighlighter({ themes: ['vitesse-dark'] }) const colors = fromShikiTheme(highlighter.getTheme('vitesse-dark')) const svg = await renderMermaid('graph TD; A-->B', colors) ``` ## Быстрый старт 1. Установите `beautiful-mermaid` в целевом проекте. 2. Используйте `renderMermaid()` для SVG или `renderMermaidAscii()` для вывода в терминал. 3. Примените встроенную тему или настройте цвета. ```ts import { renderMermaid, renderMermaidAscii, THEMES } from 'beautiful-mermaid' const svg = await renderMermaid('graph TD; A-->B', THEMES['tokyo-night']) const ascii = renderMermaidAscii('graph LR; A-->B', { useAscii: true }) ``` ## Задачи ### Рендеринг SVG - Импортируйте `renderMermaid` из пакета. - Передайте исходный текст Mermaid (автоматически определяется тип диаграммы). - Предоставьте необязательные параметры `RenderOptions` для цветов, шрифта и прозрачности. ```ts import { renderMermaid } from 'beautiful-mermaid' const svg = await renderMermaid(` sequenceDiagram Alice->>Bob: Hello `, { bg: '#1a1b26', fg: '#a9b1d6', accent: '#7aa2f7', transparent: false, font: 'Inter' }) ``` ### Рендеринг ASCII/Unicode - Импортируйте `renderMermaidAscii`. - Используйте `useAscii: true` для полной совместимости с ASCII. - Настройте `paddingX`, `paddingY` и `boxBorderPadding` для регулировки отступов. ```ts import { renderMermaidAscii } from 'beautiful-mermaid' const unicode = renderMermaidAscii('graph LR; A-->B') const ascii = renderMermaidAscii('graph LR; A-->B', { useAscii: true }) ``` ### Оформление с использованием двух цветов - Укажите только `bg` и `fg` для использования монохромной темы. - Позвольте библиотеке автоматически выводить все остальные цвета с помощью `color-mix()`. ```ts const svg = await renderMermaid('graph TD; A-->B', { bg: '#0f0f0f', fg: '#e0e0e0' }) ``` ### Оформление с использованием дополнительных цветов - Добавьте любой из следующих параметров: `line`, `accent`, `muted`, `surface`, `border` для переопределения автоматически выводимых значений. - Укажите только те дополнительные параметры, которые важны. ```ts const svg = await renderMermaid('graph TD; A-->B', { bg: '#1a1b26', fg: '#a9b1d6', accent: '#7aa2f7', line: '#3d59a1', muted: '#565f89', surface: '#292e42', border: '#3d59a1' }) ``` ### Использование встроенных тем - Импортируйте `THEMES` и передайте одну из 15 предустановленных тем. ```ts import { renderMermaid, THEMES } from 'beautiful-mermaid' const svg = await renderMermaid('graph TD; A-->B', THEMES['tokyo-night']) ``` ### Использование тем Shiki - Загрузите тему Shiki с помощью `getSingletonHighlighter`. - Преобразуйте ее с помощью `fromShikiTheme`. - Передайте преобразованные цвета в `renderMermaid`. ```ts import { getSingletonHighlighter } from 'shiki' import { renderMermaid, fromShikiTheme } from 'beautiful-mermaid' const highlighter = await getSingletonHighlighter({ themes: ['vitesse-dark'] }) const colors = fromShikiTheme(highlighter.getTheme('vitesse-dark')) const svg = await renderMermaid('graph TD; A-->B', colors) ``` ### Использование тега `<script>` в браузере - Используйте глобальный пакет для CDN. - Получите доступ к экспортам через `beautifulMermaid`. ```html <script src="https://unpkg.com/beautiful-mermaid/dist/beautiful-mermaid.browser.global.js"></script> <script> const { renderMermaid, THEMES } = beautifulMermaid renderMermaid('graph TD; A-->B', THEMES['tokyo-night']).then(svg => { // используйте svg }) </script> ``` ### Динамическая смена темы - Обновляйте CSS-переменные SVG (без повторной отрисовки). ```js svg.style.setProperty('--bg', '#282a36') svg.style.setProperty('--fg', '#f8f8f2') ``` ### Устранение неполадок - Если рендеринг не удается, проверьте синтаксис Mermaid и тип диаграммы. - Для правильного выравнивания в терминале предпочтительнее использовать Unicode или установить `preserveDisplayWidth: true`. - При использовании в браузере убедитесь, что глобальный пакет загружен перед использованием. ## Ресурсы - Подробная информация об API и списках тем в `references/beautiful-mermaid-reference.md`. - `references/api-render.md`: Таблица параметров для `renderMermaid`, распространенные ошибки и примеры. - `references/api-ascii.md`: Таблица параметров для `renderMermaidAscii`, распространенные ошибки и примеры. - `references/themes-and-shiki.md`: Модель оформления, встроенные темы и интеграция с Shiki.