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. La ventaja principal es la simplicidad: en lugar de gestionar imágenes o herramientas visuales, escribes código que se transforma automáticamente en diagramas. Soporta flowcharts, secuencias, diagramas de Gantt, clases y entidad-relación.

Es especialmente útil en documentación técnica, wikis y repositorios de código —Forgejo, GitHub, GitLab y Obsidian ya lo soportan de forma nativa— porque mantiene los diagramas sincronizados con el texto de forma ligera y versionable.

Paso 1: plantilla de renderizado

Crea el archivo layouts/_default/_markup/render-codeblock-mermaid.html:

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

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

Esto envuelve los bloques de código detectados en un <pre> con la clase mermaid. La variable .Inner contiene el contenido del bloque; htmlEscape evita la interpretación de caracteres HTML peligrosos y safeHTML le indica a Hugo que inserte el contenido sin escapado adicional. Además, el Page Store marca si la página actual usa Mermaid.

Paso 2: cargar la librería solo cuando hace falta

Para no cargar Mermaid en todas las páginas, crea layouts/partials/extended_head.html:

{{ 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 importa la librería desde jsDelivr CDN y la inicializa automáticamente al cargar la página.

Paso 3: usar Mermaid en el contenido

Ya puedes insertar bloques de código con el identificador de lenguaje mermaid en cualquier página:

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

El resultado es un diagrama de flujo renderizado directamente en el navegador, sin imágenes externas ni dependencias de build:

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