MermaidRendering 1.26.8.18

MermaidRendering

MermaidRendering converte diagrammi Mermaid in formato SVG e PNG usando PuppeteerSharp + Chromium headless. Nessuna dipendenza da Node.js, JSDOM o browser esterni — Chromium viene scaricato automaticamente alla prima esecuzione.

Requisiti

• .NET 10.0+
• Connessione Internet (prima esecuzione: download ~130 MB Chromium)
• Linux: vedere sezione Linux — dipendenze

Installazione

Via NuGet

<PackageReference Include="MermaidRendering" Version="1.0.0" />

Da sorgente

git clone <url>
cd MermaidRendering
dotnet build

Utilizzo rapido

using MermaidRendering;

var r = new MermaidRenderer();

// SVG
string svg = r.Mermaid2SVG("graph TD; A-->B;");
File.WriteAllText("output.svg", svg);

// PNG (300 DPI, 6.67 pollici di larghezza)
byte[] png = r.Mermaid2PNG("graph TD; A-->B;");
File.WriteAllBytes("output.png", png);

// PNG a risoluzione personalizzata
byte[] png150 = r.Mermaid2PNG("graph TD; A-->B;", dpi: 150, widthInches: 4);

API

MermaidRenderer — Classe principale (sincrona)

La classe implementa IDisposable. Usare using:

using var r = new MermaidRenderer();

Il numero massimo di operazioni concorrenti è 2 (limite hardcoded via SemaphoreSlim). Oltre questo limite, le richieste accodano.

MermaidOptions — Opzioni di rendering

Temi disponibili

• MermaidTheme.Default — tema chiaro standard
• MermaidTheme.Dark — tema scuro
• MermaidTheme.Neutral — tema neutro
• MermaidTheme.Forest — tema foresta

Esempi con opzioni

// Tema scuro con sfondo
var dark = new MermaidOptions { Theme = MermaidTheme.Dark, BackgroundColor = "#1E1E1E" };
string svgDark = r.Mermaid2SVG("graph TD; A-->B;", dark);

// PNG largo 8 pollici a 300 DPI
byte[] png = r.Mermaid2PNG("graph TD; A-->B;", dpi: 300, widthInches: 8);

Diagrammi supportati

La libreria usa Mermaid.js v11 via CDN. Tutti i tipi di diagramma supportati da Mermaid funzionano.

Legenda

• ✅ Testato — verificato su Windows + Linux
• ❌ Non funzionante — limiti di mermaid.js/Chromium

Piattaforme supportate

Linux — dipendenze

Prima esecuzione su Linux (richiede root una tantum):

sudo bash InstallMermaidRendering.sh

Oppure manualmente:

sudo apt-get install -y libnss3 libatk-bridge2.0-0 libdrm2 libxkbcommon0 libgbm1

Architettura

C# (MermaidRenderer)
    │
    ├── Mermaid2SVG(code, opts)
    │       └── PuppeteerSharp → Chromium headless
    │             └── pagina HTML con mermaid.js (CDN)
    │             └── evaluate(renderMermaid) → SVG
    │
    └── Mermaid2PNG(code, dpi, widthInches, opts)
            ├── Mermaid2SVG() → SVG
            └── Chromium screenshot della pagina con SVG embedded

Flusso inizializzazione

1. new BrowserFetcher().DownloadAsync() scarica Chromium (~130 MB) se non presente
2. Puppeteer.LaunchAsync() avvia Chromium headless
3. Crea una pagina e carica mermaid-render.html (embedded resource)
4. La pagina importa mermaid.js da CDN (cdn.jsdelivr.net)
5. Tutte le chiamate successive riutilizzano browser e pagina

Files nel progetto

MermaidRendering/
├── MermaidRenderer.cs          ~240 righe (API pubblica)
├── MermaidOptions.cs           Opzioni rendering
├── MermaidRendering.csproj     net10.0, solo PuppeteerSharp
├── Resources/mermaid-render.html  Pagina HTML per Chromium
├── InstallMermaidRendering.sh  Script install dipendenze Linux
└── README.md

Concorrenza

• Massimo 2 operazioni contemporanee (SVG o PNG)
• Oltre il limite, le richieste attendono in coda
• Chromium e pagina sono condivisi (singleton)

HtmlRenderer — HTML → PNG

Oltre a Mermaid, la libreria espone HtmlRenderer.RenderHtml() per convertire qualsiasi contenuto HTML in PNG, riutilizzando lo stesso browser Chromium.

using MermaidRendering;

var html = @"<h1 style='color:blue'>Titolo</h1><p>Testo del paragrafo.</p>";
byte[] png = HtmlRenderer.RenderHtml(
    html: html,
    dpi: 300,
    widthInches: 6.67,
    backgroundColor: "#FFFFFF"
);
File.WriteAllBytes("output.png", png);

Parametri

Se heightInches è null (default), l'altezza viene calcolata automaticamente dal contenuto (Chromium misura scrollHeight del body).
Se heightInches è impostato, il PNG ha esattamente quell'altezza e il contenuto HTML è centrato verticalmente con flexbox.

Sostituzione immagini

Il parametro images permette di incorporare immagini nell'HTML senza file esterni:

var logo = File.ReadAllBytes("logo.svg");
byte[] png = HtmlRenderer.RenderHtml(
    html: "<img src=\"logo.svg\">",
    images: new[] { ("logo.svg", logo) }
);

La sostituzione è testuale (no regex): ogni occorrenza di "logo.svg" (apici inclusi) viene sostituita con "data:image/svg+xml;base64,...". Il MIME type è dedotto dall'estensione del file.

Pulizia risorse

Il browser Chromium rimane attivo per riutilizzo tra chiamate. Per terminarlo esplicitamente:

HtmlRenderer.Shutdown();

Sviluppo

Prerequisiti

• .NET SDK 10.0+
• Connessione Internet (CDN per mermaid.js + download Chromium)

Test

dotnet build
dotnet run --project ../MermaidRendering-Test/MermaidRendering.Test.csproj

Licenza

MIT