Beautiful‑Mermaid: Renderizador Ultra Rápido y completamente temable de diagramas Mermaid

Beautiful‑Mermaid es una pequeña biblioteca de puro TypeScript que convierte la DSL de Mermaid en hermosos SVG o arte ASCII compatible con terminales, con una huella mínima. Es el motor que potencia el soporte de diagramas de Craft Agents, ofreciendo más de 100 diagramas en menos de 500 ms, 15 temas predefinidos y un cambio de tema en vivo, basado en CSS, sin interrupciones.

Características clave

• Sin dependencias DOM – Pure TS, funciona en Node, navegador o CLI.
• Renderizado rápido – Empaquetador ultra ligero, más de 100 diagramas en menos de medio segundo.
• Doble salida – SVG para interfaces ricas, ASCII/Unicode para terminales.
• Temas ricos – Modo mono de dos colores, modo enriquecido, 15 temas incorporados, integración con Shiki.
• Cambio de tema en vivo – Propiedades CSS personalizadas, sin volver a renderizar.
• Soporte multi-diagrama – Diagramas de flujo, Estado, Secuencia, Clase y ER.

Empezando

# Instala usando tu gestor de paquetes favorito
npm i beautiful-mermaid
# o
bun add beautiful-mermaid
# o
pnpm add beautiful-mermaid

Renderizando un SVG

import { renderMermaid } from 'beautiful-mermaid';

const diagram = `
sequenceDiagram
Alice->>Bob: Hello Bob!
Bob-->>Alice: Hi Alice!
`;

const svg = await renderMermaid(diagram, {
  // Puedes elegir un tema pre-construido
  ...THEMES['tokyo-night'],
  // o proporcionar un esquema de colores personalizado
  bg: '#1a1b26',
  fg: '#a9b1d6',
});

document.body.innerHTML = svg;

Renderizando ASCII para un CLI

import { renderMermaidAscii } from 'beautiful-mermaid';

const ascii = renderMermaidAscii(`graph LR; A --> B --> C`);
console.log(ascii);

┌───┐ ┌───┐ ┌───┐
│ A │────►│ B │────►│ C │
└───┘ └───┘ └───┘

Tematización personalizada con variables CSS

Todos los colores de los temas son propiedades CSS personalizadas en el elemento raíz <svg>, lo que permite cambios de tema instantáneos:

svg.style.setProperty('--bg', '#282a36');
svg.style.setProperty('--fg', '#f8f8f2');

El SVG se actualiza instantáneamente sin volver a renderizar.

Integrando temas Shiki

Si prefieres temas de estilo VS Code, simplemente importa un tema Shiki y conviértelo:

import { getSingletonHighlighter } from 'shiki';
import { renderMermaid, fromShikiTheme } from 'beautiful-mermaid';

const highlighter = await getSingletonHighlighter({
  themes: ['dracula', 'catppuccin-mocha'],
});

const colors = fromShikiTheme(highlighter.getTheme('dracula'));
const svg = await renderMermaid(diagram, colors);

Ejemplo: Renderizando un diagrama de flujo

const flow = `
flowchart TD
  Start --> Decide{Decision}
  Decide -->|Yes| Process
  Decide -->|No| End
`;

const svg = await renderMermaid(flow, THEMES['one-dark']);

¿Por qué Beautiful‑Mermaid?

• Simplicidad – Sin dependencias pesadas, puro TS.
• Rendimiento – El benchmark muestra más de 100 diagramas en menos de 500 ms.
• Versatilidad – Funciona en web, Node o cualquier entorno.
• Extensibilidad – Agrega tus propios temas, integra con Shiki, cambia colores en vivo.
• Código abierto – Licenciado MIT, amigable con la comunidad.

Casos de uso

• Herramientas de desarrollo – Inserta diagramas de flujo interactivos en extensiones de VS Code.
• Documentación – Genera diagramas SVG para MkDocs o Docsify.
• Utilidades CLI – Imprime diagramas legibles en los logs de terminal.
• Chatbots – Visualiza lógica en la IU de chat cuando el usuario solicita ayuda con diagramas.

Comunidad y Contribución

Beautiful‑Mermaid es un proyecto activo en GitHub. Las contribuciones son bienvenidas a través de issues y pull requests. Consulta la thread de issues para tareas abiertas o la guía de contribución.

Resumen

• Instala beautiful-mermaid.
• Llama a renderMermaid() para SVG o a renderMermaidAscii() para texto.
• Usa temas incorporados o colores personalizados.
• Cambia temas en tiempo de ejecución con variables CSS.
• Aprovecha Shiki para los colores de los temas de VS Code.

Con Beautiful‑Mermaid puedes convertir texto Mermaid plano en una experiencia visual impresionante—ya sea dentro de un navegador, un terminal o en cualquier otro lugar donde lo necesites.