Beautiful‑Mermaid : un rendu ultra‑rapide et entièrement thématisable des diagrammes Mermaid

Beautiful‑Mermaid est une petite bibliothèque pure en TypeScript qui transforme le DSL Mermaid en magnifiques SVG ou en art ASCII convivial pour le terminal, tout en gardant une empreinte minimale. C’est le moteur qui alimente le support de diagrammes des Agents Craft, offrant plus de 100 diagrammes en moins de 500 ms, 15 thèmes prédéfinis, et un changement de thème en direct basé sur CSS.

Fonctionnalités clés

• Aucune dépendance DOM – TS pur, fonctionne en Node, navigateur ou CLI.
• Rendu rapide – Bundle ultra‑léger, plus de 100 diagrammes en moins d’une demi‑seconde.
• Double sortie – SVG pour UI riches, ASCII/Unicode pour terminaux.
• Thématisation riche – Mode mono‑couleur à deux couleurs, mode enrichi, 15 thèmes intégrés, intégration Shiki.
• Changement de thème en direct – Propriétés CSS personnalisées, pas de re‑rendu.
• Support multi‑diagrammes – Flux, État, Séquence, Classe et ER.

Premiers pas

# Installer via votre gestionnaire de paquets préféré
npm i beautiful-mermaid
# ou
bun add beautiful-mermaid
# ou
pnpm add beautiful-mermaid

Rendu d’un SVG

import { renderMermaid } from 'beautiful-mermaid';

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

const svg = await renderMermaid(diagram, {
  // Vous pouvez choisir un thème préconstruit
  ...THEMES['tokyo-night'],
  // ou fournir un schéma de couleurs personnalisé
  bg: '#1a1b26',
  fg: '#a9b1d6',
});

document.body.innerHTML = svg;

Rendu ASCII pour une CLI

import { renderMermaidAscii } from 'beautiful-mermaid';

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

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

Thématisation personnalisée avec des variables CSS

Toutes les couleurs du thème sont des propriétés CSS personnalisées sur l'élément racine <svg>, permettant des changements instantanés en direct :

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

Le SVG se met à jour instantanément sans re‑rendu.

Intégration des thèmes Shiki

Si vous préférez les thèmes sur le style VS Code, il suffit d'importer un thème Shiki et de le convertir :

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);

Exemple : rendu d’un diagramme d’organigramme

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

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

Pourquoi Beautiful‑Mermaid ?

• Simplicité – Pas de dépendances lourdes, pur TS.
• Performance – Le benchmark montre plus de 100 diagrammes < 500 ms.
• Polyvalence – Fonctionne sur le Web, Node ou tout autre environnement.
• Extensibilité – Ajoutez vos propres thèmes, intégrez Shiki, changez les couleurs en direct.
• Open‑Source – Licence MIT, convivial pour la communauté.

Cas d’usage

• Outils de développement – Intégrez des organigrammes interactifs dans les extensions VS Code.
• Documentation – Générez des diagrammes SVG pour MkDocs ou Docsify.
• Utilitaires CLI – Affichez des diagrammes lisibles par l’homme dans les logs de terminal.
• Chatbots – Visualisez la logique dans l’interface de chat quand l’utilisateur demande de l’aide en diagramme.

Communauté & Contribution

Beautiful‑Mermaid est un projet actif sur GitHub. Les contributions sont les bienvenues via issues et pull request. Consultez le fil des issues pour les tâches ouvertes ou le guide de contribution.

TL;DR

• Installez beautiful-mermaid.
• Appelez renderMermaid() pour SVG ou renderMermaidAscii() pour texte.
• Utilisez les thèmes intégrés ou des couleurs personnalisées.
• Changez de thème en temps réel avec les variables CSS.
• Profitez de Shiki pour les couleurs de thème VS Code.

Avec Beautiful‑Mermaid vous pouvez transformer du texte Mermaid ordinaire en une expérience visuelle époustouflante – que ce soit dans un navigateur, un terminal ou partout où vous en avez besoin.