Iconos SVG personalizados en Mermaid: registra tu diseño

Para utilizar tu propio icono SVG en Mermaid, coloca su contenido gráfico y sus dimensiones de coordenadas en un conjunto de iconos Iconify, llama a mermaid.registerIconPacks() y referencia el nombre registrado en el diagrama. Un nombre de archivo SVG por sí solo no registra un icono.

Este proceso encaja en una página o aplicación donde controlas el JavaScript de Mermaid. Un editor Markdown alojado puede exponer solo el texto del diagrama, así que comprueba sus opciones de integración antes de preparar toda una colección de iconos. Empieza con un pictograma sencillo y un conector. Mantén las etiquetas del diagrama en Mermaid para que sigan separadas del diseño.

Comprueba dónde puedes registrar el paquete

La API de registro de Mermaid acepta directamente un conjunto de iconos o un cargador que lo devuelva. El name registrado se convierte en el prefijo utilizado en el diagrama. En este ejemplo, el paquete es garden y su icono es leaf, lo que da la referencia garden:leaf.

El registro corresponde al JavaScript que prepara el renderizador. Pegar ese JavaScript en un bloque de código Mermaid no es la misma operación. Si tu plataforma de publicación no permite configurar su renderizador, utiliza sus conjuntos de iconos compatibles o renderiza el diagrama mediante un proceso que controles e inserta el resultado exportado. Conserva el código fuente Mermaid junto al resultado para editar después.

Para esta guía, utiliza una página HTML corriente servida por HTTP local. Carga desde una CDN un módulo fijado de Mermaid 12.0.0 y por tanto necesita acceso a la red. Una aplicación de producción puede empaquetar la versión de Mermaid elegida. Prueba esa versión y la política de seguridad de contenido de tu alojamiento antes de adoptar el ejemplo.

Conserva las coordenadas de dibujo del SVG

Esta es la hoja original utilizada en nuestra prueba. Guárdala como leaf.svg si quieres inspeccionar el diseño por separado:

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

El campo body de Iconify contiene el contenido del interior de la raíz SVG, sin ese elemento exterior <svg>. El rectángulo de coordenadas se transmite por separado como left, top, width y height. Para este archivo, el origen es cero y las dimensiones son 32 por 24.

No copies en su lugar el tamaño CSS renderizado. Un archivo mostrado a 64 píxeles puede seguir teniendo un viewBox de 0 0 32 24. Sus trazados se dibujaron en este último sistema de coordenadas. Para un origen distinto de cero, conserva también los valores correspondientes de left y top, o traslada deliberadamente el diseño a un lienzo con origen cero antes de empaquetarlo.

Un conjunto Iconify contiene un prefix y un objeto icons. Cada clave de icono da nombre a su dibujo. Las dimensiones explícitas son útiles aquí: si no las proporciona ni el icono ni el conjunto, los valores predeterminados de ancho y alto de Iconify son 16. Eso puede recortar un diseño dibujado para un lienzo mayor.

Si preparas una familia de pictogramas, termina primero sus contornos, márgenes y peso visual. Nuestra guía de preparación de kits de interfaz SVG explica esas decisiones sobre el diseño original. Empaquetar un icono no mejora su silueta.

Ejecuta un ejemplo completo de dos nodos

Guarda lo siguiente como index.html en una carpeta nueva. Si tienes Python disponible, ejecuta python3 -m http.server 8000 en esa carpeta y después abre http://localhost:8000 en el navegador.

<!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>

Deberías ver la hoja junto a un símbolo de base de datos, conectados de Source a Library. La hoja procede del paquete registrado; database es uno de los iconos de arquitectura integrados de Mermaid. La referencia de sintaxis de arquitectura describe los nombres de iconos entre paréntesis, las etiquetas entre corchetes y los lados de los servicios utilizados para las conexiones.

El ejemplo desactiva el renderizado automático y realiza una llamada explícita a render() después del registro. Así el orden queda visible durante las pruebas. Al integrarlo en un sitio existente, asegúrate de que el registro y la llamada de renderizado utilicen la misma instancia de Mermaid.

Es un dibujo pequeño y de confianza creado para el ejemplo. Para una colección grande de iconos, utiliza las herramientas de importación y limpieza de Iconify en lugar de suponer que cualquier SVG exportado puede reducirse a una cadena de trazados sin más trabajo. Las fuentes, imágenes externas, estilos y definiciones referenciadas merecen una inspección independiente.

Compara un registro ausente con unas dimensiones ausentes

Renderizamos tres copias de este diagrama en documentos de navegador separados con Mermaid 12.0.0. La primera omitía el registro. La segunda registraba los dos trazados de la hoja, pero omitía sus dimensiones. La tercera registraba los mismos trazados con width: 32 y height: 24.

En el primer renderizado, Mermaid mostró un signo de interrogación donde debía aparecer la hoja personalizada. El trazado de la hoja no estaba en la salida. En el segundo, la salida contenía ese trazado dentro de un SVG con viewBox="0 0 16 16" y la hoja estaba visiblemente recortada. En el tercero, el icono utilizaba viewBox="0 0 32 24" y aparecía la hoja completa.

Estas observaciones describen este ejemplo y versión. No establecen que todos los alojamientos indiquen del mismo modo un icono no disponible. El ejemplo también utiliza trazados SVG escritos a mano; no es un resultado de conversión de PerfectVector.

Conserva una copia funcional del ejemplo mínimo antes de añadir más iconos. Cambia una propiedad del paquete cada vez; de lo contrario, una corrección de nombre puede ocultar un problema independiente de tamaño.

Incorpora un diseño rasterizado cuando sea necesario

Si tu pictograma personalizado solo se conserva como PNG o JPG, el proceso de clipart a SVG de PerfectVector puede ayudar a recuperar contornos editables. Recorta una copia hasta el pictograma, previsualiza el resultado vectorial e inspecciona la silueta, los huecos interiores y las formas de fondo indeseadas. Después abre el SVG en un editor y prepara la versión pequeña que utilizarás en el diagrama.

Conserva ese original SVG editable. Empaqueta su contenido gráfico y sus coordenadas solo después de que se lea claramente al tamaño de icono previsto. Un símbolo geométrico sencillo puede ser más rápido de redibujar; una fotografía puede ser más clara como imagen independiente. Si ya tienes un SVG adecuado, empieza por el paso de empaquetado.

La vectorización no recupera los nombres de servicio, las relaciones ni las direcciones de los conectores del diagrama. Mantén esos datos en el código fuente Mermaid. Para un editor de lienzo con otro comportamiento de formas, consulta formas SVG personalizadas en draw.io. Para iconos reutilizables en una página web corriente, un sprite de símbolos SVG es otro método de empaquetado. Para diagramas basados en DOT, comprueba la entrega de imágenes de nodos SVG en Graphviz para saber si el diseño personalizado acompaña al gráfico exportado.

Antes de entregar el diagrama, vuelve a abrirlo mediante el proceso real de publicación. Confirma que el icono carga, cabe toda la silueta, ambas etiquetas son legibles y el conector apunta en la dirección correcta. Un renderizado local correcto es la comprobación inicial, seguida de una comprobación del destino.

Preguntas frecuentes

¿Puedo poner un nombre de archivo SVG dentro de una referencia de icono Mermaid? Para el proceso de paquetes de iconos registrados, utiliza un nombre de paquete y una clave de icono como garden:leaf. Prepara el dibujo SVG como datos de icono y registra ese paquete en el JavaScript del renderizador.

¿Por qué se recorta mi icono personalizado de Mermaid? Compara el viewBox original con las propiedades de coordenadas de los datos del icono. Si faltan dimensiones tanto en el icono como en su conjunto, los valores predeterminados de ancho y alto son 16, que pueden ser demasiado pequeños para el dibujo.

¿Funciona esto en todos los editores Markdown alojados? No. El alojamiento debe admitir la sintaxis del diagrama y ofrecer una forma de registrar el paquete necesario, o incluirlo ya. Prueba el destino real de publicación en lugar de asumir que comparte tu configuración local.

Fuentes

1. Mermaid — Registrar paquetes de iconos — documenta datos directos de iconos, cargadores y nombres de registro.
2. Mermaid — Diagramas de arquitectura — define iconos de servicios, etiquetas nativas, iconos integrados y sintaxis de conexiones.
3. Iconify — IconifyIcon — define el contenido gráfico sin el contenedor SVG y las propiedades de coordenadas.
4. Iconify — IconifyJSON — define la estructura del paquete y las dimensiones predeterminadas que heredan los iconos.

¿Tienes un pictograma para el diagrama que solo existe rasterizado? Prepara una alternativa SVG con PerfectVector, inspecciona su silueta y huecos y después registra un icono y verifica sus límites y etiqueta en tu renderizador Mermaid final.