Activar el soporte de Mermaid en Hugo

Mermaid es una librería de JavaScript que permite crear diagramas a partir de texto usando una sintaxis tipo Markdown. Su idea principal es que, en lugar de arrastrar y soltar elementos visuales o pelearte con imágenes, escribes un bloque de código con una sintaxis sencilla, y Mermaid lo transforma automáticamente en el diagrama correspondiente. Tiene soporte para multitud de diagramas: flujo, secuencia, Gantt, clases, ER…

Se usa mucho en documentación técnica, wikis y repositorios de código (Forgejo, GitHub, GitLab o Obsidian ya la soportan) porque facilita mantener diagramas sincronizados con el texto, de forma ligera y versionable.

Aunque Hugo, de entrada no tiene soporte para Mermaid, es muy fácil añadirlo:

Paso 1:

Lo primero es crear una plantilla de renderizado personalizada creando el fichero layouts/_default/_markup/render-codeblock-mermaid.html y añadiendo:

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

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

Esto hace que cuando se detecte un bloque de código se envuelva en un <pre> con la clase mermaid. .Inner es el contenido real del bloque de código en Markdown. htmlEscape evita que se interpreten caracteres peligrosos como HTML y safeHTML indica a Hugo que ese contenido puede insertarse tal cual, sin más escapes. Además se marca en el Page Store que esta página usa Mermaid.

Paso 2:

Ya tenemos resuelta una parte, ahora hay que hacer que se cargue la librería de Mermaid sólo en las páginas que lo necesitan. Para ello creamos el fichero layouts/partials/extended_head.html con lo siguiente:

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

Esto importará la librería desde el CDN de jsDelivr y la inicializará automáticamente cuando se cargue la página.

Paso 3:

Ahora ya puedes insertar un bloque de código con el lenguaje mermaid en cualquier página de Hugo:

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

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