Activar Mermaid en Hugo · José San Juan

De vez en cuando necesito meter un diagrama en una entrada. Podría dibujarlo fuera del blog y subirlo como imagen, pero eso supone guardar el archivo original, exportarlo cada vez que cambia algo y acordarme de actualizar ambas versiones. Para un esquema que seguramente retocaré más adelante, da bastante pereza.

Mermaid resuelve justo ese problema: el diagrama se escribe como texto dentro del propio Markdown. Así queda junto al artículo, se puede guardar en Git y modificar sin abrir otra aplicación.

Hugo no interpreta estos bloques por sí solo, pero añadir el soporte es bastante directo. En mi caso uso PaperMod, aunque la idea sirve para cualquier tema que respete los puntos de extensión habituales de Hugo.

Enseñarle a Hugo qué hacer con un bloque Mermaid

Lo primero es crear layouts/_default/_markup/render-codeblock-mermaid.html:

<pre class="mermaid">
  {{- .Inner | htmlEscape | safeHTML }}
</pre>

{{ .Page.Store.Set "mermaidEnable" true }}

Hugo usará esta plantilla cada vez que encuentre un bloque de código marcado como mermaid. El contenido acaba dentro de un <pre> con la clase que busca la librería.

La última línea guarda una pequeña marca en la página. No hace nada visible, pero permite saber más tarde si esa entrada contiene algún diagrama. Esto viene bien para no descargar Mermaid en el resto del sitio.

Cargar la librería solo en las páginas que la usan

PaperMod permite añadir contenido al <head> mediante layouts/partials/extended_head.html. Ahí podemos consultar la marca anterior:

{{ if .Store.Get "mermaidEnable" }}
<script type="module">
  import mermaid from "https://cdn.jsdelivr.net/npm/[email protected]/+esm";

  mermaid.initialize({
    startOnLoad: true,
  });
</script>
{{ end }}

Con esto, el navegador solo pide Mermaid cuando realmente hay algo que dibujar. En un blog con pocos diagramas no cambia la vida, pero tampoco tiene sentido hacer que cada visita descargue una librería que no va a usar.

Escribir el diagrama

A partir de aquí basta con añadir un bloque como este a cualquier Markdown:

```mermaid
graph TD;
  A-->B;
  A-->C;
  B-->D;
  C-->D;
```

Y el navegador lo convierte en el diagrama:

graph TD;
  A-->B;
  A-->C;
  B-->D;
  C-->D;

No hay archivos adicionales ni exportaciones que repetir. Si cambio una flecha, edito dos caracteres en el artículo y listo.