Icônes SVG Mermaid : enregistrer ton propre dessin

Pour utiliser ta propre icône SVG dans Mermaid, place son contenu graphique et les dimensions de son espace de coordonnées dans un jeu d’icônes Iconify, appelle mermaid.registerIconPacks() et référence le nom enregistré dans le diagramme. Un nom de fichier SVG seul n’enregistre pas une icône.

Cette procédure convient à une page ou application dont tu contrôles le JavaScript Mermaid. Un éditeur Markdown hébergé peut ne proposer que le texte du diagramme ; vérifie donc ses options d’intégration avant de préparer toute une collection d’icônes. Commence avec un pictogramme simple et un connecteur. Garde les libellés du diagramme dans Mermaid pour qu’ils restent distincts du dessin.

Vérifier où tu peux enregistrer le jeu

L’API d’enregistrement de Mermaid accepte directement un jeu d’icônes ou un chargeur qui en renvoie un. Le name enregistré devient le préfixe utilisé dans ton diagramme. Dans cet exemple, le jeu est garden et son icône est leaf, ce qui donne la référence garden:leaf.

L’enregistrement appartient au JavaScript qui prépare le moteur de rendu. Coller ce JavaScript dans un bloc de code Mermaid n’effectue pas la même opération. Si ta plateforme de publication ne te laisse pas configurer son moteur, utilise ses jeux d’icônes pris en charge ou rends le diagramme dans une procédure que tu contrôles, puis insère le résultat exporté. Garde la source Mermaid avec ce résultat pour les modifications ultérieures.

Pour ce guide, utilise une page HTML ordinaire servie en HTTP local. Elle charge un module Mermaid 12.0.0 à version fixée depuis un CDN et nécessite donc un accès réseau. Une application de production peut plutôt intégrer la version Mermaid de son choix. Teste cette version et la politique de sécurité du contenu de ton hébergement avant d’adopter l’exemple.

Préserver les coordonnées de dessin du SVG

Voici la feuille originale utilisée dans notre test. Enregistre-la sous leaf.svg si tu veux examiner le dessin séparément :

<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 32 24">
  <path fill="#167c72"
    d="M3 19C1 5 14 2 29 3C29 17 17 25 3 19Z"/>
  <path fill="none" stroke="#d7f1ca" stroke-width="1.8"
    d="M5 18L23 7"/>
</svg>

Le champ body d’Iconify contient le contenu à l’intérieur de la racine SVG, sans cet élément <svg> extérieur. Le rectangle de coordonnées est transmis séparément via left, top, width et height. Pour ce fichier, l’origine est zéro et les dimensions sont de 32 sur 24.

Ne copie pas à la place la taille CSS affichée. Un fichier affiché à 64 pixels peut quand même avoir un viewBox de 0 0 32 24. Ses tracés ont été dessinés dans ce dernier système de coordonnées. Pour une origine non nulle, préserve aussi les valeurs left et top correspondantes, ou translate volontairement le dessin vers un canevas d’origine zéro avant de l’empaqueter.

Un jeu Iconify contient un prefix et un objet icons. Chaque clé d’icône nomme son dessin. Des dimensions explicites sont utiles ici : si ni l’icône ni le jeu ne les fournissent, les valeurs par défaut de largeur et de hauteur d’Iconify sont de 16. Cela peut rogner un dessin conçu pour un canevas plus grand.

Si tu prépares une famille de pictogrammes, termine d’abord leurs contours, marges et poids visuel. Notre guide de préparation SVG pour kits d’interface traite de ces décisions sur les dessins source. Empaqueter une icône n’améliore pas sa silhouette.

Exécuter un exemple complet à deux nœuds

Enregistre ce qui suit sous index.html dans un nouveau dossier. Si Python est disponible, lance python3 -m http.server 8000 dans ce dossier, puis ouvre http://localhost:8000 dans ton navigateur.

<!doctype html>
<meta charset="utf-8">
<title>Custom Mermaid leaf icon</title>
<div id="diagram"></div>
 
<script type="module">
import mermaid from
  'https://cdn.jsdelivr.net/npm/mermaid@12.0.0/dist/mermaid.esm.min.mjs';
 
const icons = {
  prefix: 'garden',
  icons: {
    leaf: {
      width: 32,
      height: 24,
      body: '<path fill="#167c72" d="M3 19C1 5 14 2 29 3C29 17 17 25 3 19Z"/>' +
        '<path fill="none" stroke="#d7f1ca" stroke-width="1.8" d="M5 18L23 7"/>'
    }
  }
};
 
mermaid.registerIconPacks([{ name: 'garden', icons }]);
mermaid.initialize({ startOnLoad: false, theme: 'neutral' });
 
const definition = `architecture-beta
  service source(garden:leaf)[Source]
  service library(database)[Library]
  source:R --> L:library`;
 
const { svg } = await mermaid.render('garden-diagram', definition);
document.querySelector('#diagram').innerHTML = svg;
</script>

Tu devrais voir la feuille à côté d’un symbole de base de données, reliés de Source à Library. La feuille provient du jeu enregistré ; database est une des icônes d’architecture intégrées à Mermaid. La référence de syntaxe d’architecture décrit les noms d’icônes entre parenthèses, les libellés entre crochets et les côtés des services utilisés pour les liaisons.

L’exemple désactive le rendu automatique et effectue un seul appel explicite à render() après l’enregistrement. L’ordre reste ainsi visible pendant le test. Lors de l’intégration à un site existant, assure-toi que l’enregistrement et l’appel de rendu utilisent la même instance Mermaid.

Il s’agit d’un petit dessin fiable créé pour l’exemple. Pour une grande collection d’icônes, utilise les outils d’import et de nettoyage d’Iconify plutôt que de supposer que tout SVG exporté peut être réduit à une chaîne de tracé sans autre travail. Les polices, images externes, styles et définitions référencées méritent un examen distinct.

Comparer l’absence d’enregistrement et l’absence de dimensions

Nous avons rendu trois copies de ce diagramme dans des documents navigateur séparés avec Mermaid 12.0.0. La première omettait l’enregistrement. La deuxième enregistrait les deux tracés de la feuille, mais omettait leurs dimensions. La troisième enregistrait les mêmes tracés avec width: 32 et height: 24.

Dans le premier rendu, Mermaid affichait un point d’interrogation à l’endroit de la feuille personnalisée. Le tracé de la feuille était absent de la sortie. Dans le deuxième, la sortie contenait ce tracé dans un SVG avec viewBox="0 0 16 16", et la feuille était visiblement rognée. Dans le troisième, l’icône utilisait viewBox="0 0 32 24" et la feuille complète apparaissait.

Ces observations décrivent cet exemple et cette version. Elles n’établissent pas que chaque hébergement signale de la même façon une icône indisponible. L’exemple utilise aussi des tracés SVG écrits à la main ; ce n’est pas un résultat de conversion PerfectVector.

Garde une copie fonctionnelle de l’exemple minimal avant d’ajouter des icônes. Change une propriété du jeu à la fois ; sinon une correction de nom peut masquer un autre problème de taille.

Intégrer un dessin matriciel à la procédure si nécessaire

Si ton pictogramme personnalisé n’existe plus qu’en PNG ou JPG, la procédure clipart vers SVG de PerfectVector peut aider à reconstruire des contours éditables. Recadre une copie sur le pictogramme, affiche le résultat vectoriel et examine la silhouette, les espaces intérieurs et les formes de fond indésirables. Ouvre ensuite le SVG dans un éditeur et prépare la petite version prévue pour le diagramme.

Garde cet original SVG éditable. Empaquette son contenu graphique et ses coordonnées seulement lorsqu’il se lit clairement à la taille d’icône prévue. Un symbole géométrique simple peut être plus rapide à redessiner ; une photographie peut être plus claire comme image distincte. Si tu as déjà un dessin SVG adapté, commence à l’étape d’empaquetage.

La vectorisation ne retrouve pas les noms de services, les relations ni le sens des connecteurs du diagramme. Garde-les dans la source Mermaid. Pour un éditeur à canevas dont les formes ont un autre comportement, consulte les formes SVG personnalisées dans draw.io. Pour des icônes réutilisables dans une page web ordinaire, un sprite de symboles SVG est une autre méthode d’empaquetage. Pour les diagrammes fondés sur DOT, consulte la livraison d’images de nœuds SVG Graphviz pour voir si le dessin personnalisé accompagne le graphe exporté.

Avant de transmettre ton diagramme, rouvre-le avec la procédure réelle de publication. Confirme que l’icône se charge, que toute la silhouette tient, que les deux libellés sont lisibles et que le connecteur pointe dans le bon sens. Un rendu local réussi est ta première vérification, suivie d’une vérification de destination.

FAQ

Puis-je mettre un nom de fichier SVG dans une référence d’icône Mermaid ? Pour la procédure de jeu d’icônes enregistré, utilise un nom de jeu et une clé d’icône comme garden:leaf. Prépare le dessin SVG comme données d’icône et enregistre ce jeu dans le JavaScript du moteur de rendu.

Pourquoi mon icône Mermaid personnalisée est-elle rognée ? Compare le viewBox source aux propriétés de coordonnées des données de l’icône. Si les dimensions manquent à la fois dans l’icône et dans son jeu, les valeurs par défaut de largeur et de hauteur sont de 16, ce qui peut être trop petit pour le dessin.

Cela fonctionne-t-il dans tous les éditeurs Markdown hébergés ? Non. L’hébergement doit prendre en charge la syntaxe du diagramme et fournir une façon d’enregistrer le jeu nécessaire, ou l’inclure déjà. Teste la destination réelle de publication au lieu de supposer qu’elle partage ta configuration locale.

Sources

1. Mermaid — Enregistrer des jeux d’icônes — Décrit les données d’icône directes, les chargeurs et les noms d’enregistrement.
2. Mermaid — Diagrammes d’architecture — Définit les icônes de services, libellés natifs, icônes intégrées et syntaxe des liaisons.
3. Iconify — IconifyIcon — Définit le contenu graphique sans enveloppe SVG et les propriétés de coordonnées.
4. Iconify — IconifyJSON — Définit la structure du jeu et les dimensions par défaut héritées par les icônes.

Tu as un pictogramme uniquement matriciel pour ton diagramme ? Prépare un SVG candidat avec PerfectVector, examine sa silhouette et ses espaces, puis enregistre une icône et vérifie ses limites et son libellé dans ton moteur Mermaid final.