Por qué he pasado de Zensical a Hugo

Zensical me funcionó bien. Escribir en Markdown plano, un Makefile corto y un sitio decente en minutos: justo lo que pedía cuando empecé este cuaderno. Pero Zensical, igual que MkDocs, piensa en documentación, y esto hace tiempo que es un blog.

Una herramienta de documentación te da un índice perfecto. Un blog necesita fechas, categorías y un RSS que funcione sin que tú lo mantengas.

Lo que sigue es por qué he cambiado, qué he ganado y qué me encontré por el camino.

Lo que me empujó

#

Las listas escritas a mano

#

Cada cuaderno tenía su página índice con la lista de entradas, la fecha y un contador. Había además un archivo cronológico y una sección de “últimos cuadernos” en la portada. Todo a mano.

El resultado era el previsible: el índice de Desarrollo anunciaba 38 entradas cuando había seis, y la portada tenía marcadores como {{N_ENTRIES}} que nunca llegaron a rellenarse. Cada artículo nuevo suponía tocar tres o cuatro ficheros, y siempre se me olvidaba alguno.

Sintaxis que no sale de casa

#

Los avisos con !!! note, las preguntas plegables con ??? question, las rejillas de tarjetas con markdown en un <div>, los iconos :material-…:. Todo muy cómodo mientras vives dentro de ese ecosistema, y todo inútil fuera de él. Mis textos no eran Markdown portable: eran Markdown de Material.

El RSS y las etiquetas

#

El índice global de etiquetas no estaba soportado, y el feed dependía de cómo estuviera montada cada sección. Para un sitio cuyo único canal de suscripción es el RSS, eso no es un detalle.

Lo que he ganado con Hugo

#

Todo sale del front matter. Cada artículo declara su fecha y su cuaderno, y Hugo genera el resto: la lista de artículos agrupada por año, la página de cada cuaderno, las etiquetas, el RSS y el índice del buscador. Añadir una entrada es crear un fichero; no hay nada más que actualizar.

Los cuadernos son categorías, no carpetas. Antes, cada cuaderno era un directorio con su propia jerarquía. Ahora todos los artículos viven en posts/ y el cuaderno es un campo más:

---
title: "Por qué he pasado de Zensical a Hugo"
date: 2026-09-26T00:00:00+02:00
categories:
  - Desarrollo
tags:
  - hugo
---

Cambiar un artículo de cuaderno es cambiar una línea, y las URLs no dependen de dónde decidí guardarlo.

Un binario y nada más. Hugo es un único ejecutable. Nada de entornos virtuales ni de versiones de plugins que se pisan. El sitio entero se genera en unos pocos cientos de milisegundos.

Page bundles. Un artículo con imágenes es una carpeta con su index.md y sus ficheros al lado. La imagen destacada se llama feature.jpg y el tema la usa para la tarjeta, la cabecera y la vista previa al compartir. Hugo se encarga de redimensionarla.

El tema

#

Empecé con Hextra, que viene del mundo de la documentación y me dejaba demasiado cerca de donde estaba. Acabé en Blowfish: portada con tarjetas, cabeceras con imagen, modo claro y oscuro, buscador local y firma de autor. Lo tengo copiado dentro del repositorio en lugar de como submódulo, para que el despliegue no dependa de nada externo.

El despliegue

#

Aquí es donde más he simplificado:

1. Hago git push a main.
2. Un webhook de GitHub avisa al servidor.
3. Plesk trae el repositorio con una clave de despliegue de solo lectura.
4. Hugo compila directamente en la carpeta pública del sitio.

Entre el push y la web actualizada pasan unos segundos. No hay rama de artefactos ni CI intermedio.

Lo que me encontré por el camino

#

• El build no puede salir a internet. Hugo se ejecuta en un entorno aislado sin certificados raíz, y cualquier recurso que el tema intentara descargar de un CDN rompía el build con un error de TLS. La solución fue la sana: que el build no descargue nada. Todo lo que necesita está en el repositorio.
• Sin nginx. El servidor solo tiene Apache, así que la caché, la compresión, la página 404 y las cabeceras de seguridad van en un .htaccess que Hugo copia en cada build desde static/.
• Los enlaces rotos. Los enlaces internos al estilo MkDocs (../otra-entrada.md) había que reescribirlos. Aproveché para comprobar todo el HTML generado: cero enlaces internos rotos.

Lo que echo de menos

#

Poco, pero algo: la navegación lateral de Zensical era muy cómoda para leer un cuaderno de principio a fin. En Hugo eso depende del tema, y Blowfish está pensado para leer entrada a entrada, no como un libro.

¿Comentarios o correcciones? info@encodigo.es.