De Hugo a Astro: migrando el sitio

Tue, 24 Mar 2026 00:00:00 GMT

Llevaba un tiempo con ganas de darle una vuelta a este sitio. El blog funcionaba bien con Hugo pero quería algo que me diera más flexibilidad para añadir funcionalidad sin salir del ecosistema JavaScript.

Por qué Hugo funcionaba bien

Hugo es una herramienta excelente. Compilación rápida, sin dependencias de Node, plantillas potentes y muchos temas disponibles. Para un blog sencillo es difícil superarlo.

El problema no era Hugo en sí, sino que cada vez que quería añadir algo ligeramente más interactivo acababa peleando con las limitaciones del sistema de plantillas o añadiendo JavaScript a mano sin mucha estructura.

Por qué Astro

Astro tiene una propuesta interesante: genera HTML estático por defecto, pero permite usar componentes y lógica JavaScript durante la construcción. Es lo mejor de los dos mundos: la velocidad de un sitio estático con la flexibilidad de un framework.

Lo que más me convenció:

Componentes .astro mezclan HTML, CSS y JavaScript en un solo archivo.
Content Collections sistema para gestionar el contenido en Markdown.
Integraciones MDX, RSS, iconos con astro-icon...
Output estático el resultado final es HTML puro.

Qué ha cambiado en el sitio

Además de cambiar el motor, he aprovechado para rediseñar el sitio desde cero:

Diseño propio en lugar de un tema.
Fotolog galería asimétrica con página de detalle para cada foto.
Soporte Mermaid para diagramas en los posts, renderizado en el cliente.
Menú responsive en móvil.
Optimización de imágenes automática mediante un script con Sharp.

La migración

No había mucho contenido que migrar, el blog estaba practicamente vacío, así que el proceso fue relativamente sencillo. Los posts en Markdown se adaptan sin cambios, solo algunos ajustes.

Las URLs de los posts cambian de /posts/nombre a /blog/nombre. Para no romper los enlaces existentes, hay una redirección 301 en public/_redirects que Cloudflare Pages aplica automáticamente:

/posts/*  /blog/:splat  301

Conclusión

El resultado es un sitio más rápido, más fácil de mantener. Hugo sigue siendo una herramienta fantástica pero para este sitio y, mis ganas de cacharrear, Astro encaja mejor con lo que quiero hacer.

Activar el soporte de Mermaid en Hugo

Sun, 07 Sep 2025 00:00:00 GMT

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;

Notas al margen