Deep Dive: Hugo – qué hace un generador de sitios estáticos, qué sustituyó a mis plugins de WordPress y cómo funciona la búsqueda sin servidor

Qué es Hugo y en qué se diferencia de WordPress, quién asumió las tareas de Yoast, Polylang y los plugins de caché, cómo funciona un buscador en un sitio sin servidor, cómo añado un artículo y actualizo Hugo – y qué trampas solo aparecieron en la operación.

Un pequeño robot sobre una cinta transportadora convierte páginas Markdown en páginas HTML terminadas y les pega etiquetas SEO; el monitor muestra Markdown → Hugo → HTML

🌐 También en: English · Deutsch · Français · Italiano · Português · Nederlands · Polski

Deep Dive de la serie en torno al Ansible Tour. El tour explica los roles; los deep dives, la técnica que hay debajo: cómo funciona, por qué se usa así aquí y qué salió mal por el camino.

A principios de noviembre este blog se mudó de WordPress sobre Kubernetes a Hugo. El experimento con cifras reales y la mudanza en sí se cuentan en otro sitio. Este artículo es la visión general que me habría gustado tener antes de empezar: qué es Hugo en realidad, quién asumió las tareas de los plugins de WordPress, cómo funciona un buscador en un sitio que no tiene ni una línea de código en el servidor, qué hago cuando añado un artículo o actualizo Hugo, y dónde me sorprendió.

Índice

🧭 Qué es Hugo

Una imprenta en lugar de una cocina

WordPress funciona como la cocina de un restaurante: cada vez que un cliente pide, PHP cocina la página a partir de la base de datos – salvo que un plugin de caché ya tenga un plato listo. Hugo funciona como una imprenta: imprime cada página una vez, por adelantado, y el servidor web solo reparte ejemplares terminados. Cuando llega un lector, no se cocina nada.

Técnicamente, Hugo es un generador de sitios estáticos: un único programa escrito en Go que lee archivos Markdown, plantillas e imágenes y escribe una carpeta llena de HTML, CSS, imágenes y feeds. Esa carpeta es el sitio web. Cualquier servidor web puede servirla; aquí es un nginx sin más.

Un binario, dos ediciones

Hugo es un único ejecutable sin dependencias – sin PHP, sin base de datos, sin Node.js. Viene en una edición estándar y otra extended; la extended añade codificación WebP y Sass. Este blog usa la edición extended, versión 0.169.0, porque cada imagen se redimensiona y se convierte a WebP durante el build.

Lo que te llevas: Hugo traslada todo el trabajo del momento de la visita al momento de la publicación. Todo lo demás en este artículo se deriva de ahí.

⚖️ Hugo frente a WordPress

PreguntaWordPressHugo
¿Cuándo se genera una página?En cada petición (o desde una caché)Una vez, en el build
¿Qué corre en el servidor?PHP, MariaDB, a menudo RedisSolo el servidor web
Superficie de ataqueLogin, admin, plugins, XML-RPC, PHPArchivos estáticos
Actualizaciones periódicasNúcleo, plugins, temas, PHPnginx; Hugo solo en la máquina de build
¿Dónde escribo?Editor en el navegadorEditor de texto, Git
Comentarios, formulariosIntegradosNecesitan un servicio externo
VelocidadCon caché: 58 ms para la portada57 ms – ninguna diferencia
Peso de la página (portada, sin imágenes)25 archivos, 198 KB3 archivos, 9,5 KB

Las cifras salen de mis propias mediciones antes de la mudanza. La velocidad no fue el motivo: un WordPress bien cacheado es igual de rápido. Los motivos fueron el resto de la tabla – ningún login que atacar, ninguna actualización de plugins cada semana, ninguna base de datos que respaldar, y una página un 95 % más pequeña.

Lo que dejé atrás: el editor en el navegador, los comentarios y la comodidad de instalar una funcionalidad con un clic.

Lo que te llevas: WordPress es un programa que produce un sitio web. Hugo produce el sitio una vez y se aparta. Que eso sea mejor depende de si necesitas lo que solo el programa en ejecución sabe hacer.

🔧 Cómo funciona Hugo

Contenido: Markdown con front matter

Cada artículo es un archivo Markdown. Arriba va el front matter, un bloque de YAML que Hugo lee como datos. Un artículo de este blog empieza así:

---
title: 'Zabbix in Containers Watches My Home Network'
slug: zabbix-in-containers-watches-my-home-network
date: '2026-11-13T15:40:00+01:00'
translationKey: zabbix-heimnetz-2026-11
description: 'Short summary for search results, at most about 155 characters.'
categories:
- linux
tags:
- zabbix
image: uploads/2026/11/zabbix-watchman.webp
imageAlt: What the picture shows, for screen readers and search engines
---

Debajo del segundo --- viene el texto. Markdown cubre títulos, listas, tablas y código; donde no llega, se permite HTML en bruto (unsafe = true en los ajustes de Goldmark), algo que importa para los artículos convertidos desde WordPress.

Carpetas, secciones y direcciones

site/
├── content/en/posts/   posts in English (one folder per language)
├── content/de/posts/   posts in German, and so on for eight languages
├── layouts/            templates: the theme
├── assets/             CSS and JavaScript, processed by Hugo
├── uploads/            images and downloads
├── i18n/               interface words per language ("Read more", "Search")
├── data/               menus, flags, footer text as JSON
└── hugo.toml           configuration

hugo.toml decide las direcciones: posts = "/:year/:month/:day/:slug/" mantiene el esquema de URL que usaba WordPress, así que no se rompió ningún enlace antiguo. Las categorías y las etiquetas son taxonomías; Hugo construye por sí solo una página para cada categoría y cada etiqueta.

Plantillas

Las plantillas usan el lenguaje de plantillas de Go. baseof.html es el marco de cada página, page.html un artículo individual, home.html la portada, y los partials son piezas reutilizables – la cabecera, la barra lateral, el <head> con todas las etiquetas meta. No uso ningún tema prefabricado: los layouts se escribieron para parecerse al antiguo tema de WordPress.

El pipeline de assets

Hugo procesa los archivos él mismo: resources.Get "css/main.css" | minify | fingerprint minifica la hoja de estilos y mete un hash en su nombre de archivo, para que los navegadores puedan cachearla para siempre. Las imágenes se redimensionan durante el build – la imagen de vista previa para redes sociales, por ejemplo, se crea a partir de la imagen del artículo a 1200 px y se va reduciendo hasta quedar por debajo de 280 KB, el límite de las vistas previas de WhatsApp.

Multilingüe desde el principio

Cada idioma tiene en hugo.toml su propia carpeta de contenido, su etiqueta y su locale. Los artículos que van juntos comparten una translationKey; con ella Hugo conoce las traducciones de cada página y construye el selector de idioma y los enlaces hreflang. Este blog tiene ya ocho idiomas – inglés, alemán, francés, español, italiano, portugués, neerlandés y polaco.

Vista previa y borradores

hugo server construye el sitio en memoria y lo sirve en localhost:1313; cada archivo guardado recarga el navegador. draft: true deja un artículo fuera del build real, y una fecha en el futuro también – más sobre eso abajo.

Lo que te llevas: contenido, plantillas y configuración son tres tipos de archivos separados. Puedes cambiar el aspecto sin tocar un solo artículo, y escribir un artículo sin saber cómo funcionan las plantillas.

🧩 Adónde fueron los plugins

En WordPress, casi cada funcionalidad era un plugin. En Hugo, una funcionalidad está integrada, son unas pocas líneas de plantilla o es un pequeño script que corre después del build.

Plugin de WordPressTareaAhora
Yoast SEOTítulo, descripción, canonical, Open Graph, datos estructuradoshead.html (una plantilla para todas las páginas)
Yoast SEOSitemapIntegrado en Hugo, plantilla sitemap.xml propia con hreflang
Yoast SEO«Tu artículo no tiene descripción»check_posts.py: el build se detiene
PolylangIdiomas, selector de idiomaIntegrado en Hugo
CompressXImágenes WebP, tamaños más pequeñosProcesamiento de imágenes de Hugo
AutoptimizeMinificar CSS, JS, HTMLhugo --minify
WP Super Cache, RedisCaché de páginas y de objetosNo hace falta – cada página ya es un archivo
Búsqueda (WordPress)Búsqueda de texto completoPagefind (siguiente sección)

SEO sin plugin

Yoast hacía tres cosas: escribía etiquetas meta, construía un sitemap y daba la lata. Las dos primeras son ahora un partial, head.html. Para cada página escribe el título (o un seoTitle más corto del front matter), la descripción, un enlace canonical, un enlace hreflang por traducción, las etiquetas Open Graph y Twitter con una imagen de vista previa generada, las fechas del artículo y un bloque JSON-LD con los mismos datos estructurados que producía Yoast (Article, WebPage, BreadcrumbList, Person). Es un único archivo, y es el mismo para todas las páginas – sin pantalla de ajustes por artículo.

Dar la lata se trasladó al build: tools/check_posts.py detiene el build si a un artículo le falta título, descripción, imagen, texto de imagen, clave de traducción o fecha, o si el archivo de imagen no existe, y avisa cuando una descripción se vuelve demasiado larga o falta una traducción.

Extensiones en Hugo

Hugo no tiene tienda de plugins, pero sí puntos de extensión:

  • Temas y Hugo Modules – aspectos completos o piezas de uno, incorporados como una dependencia. Este blog monta sus propias carpetas mediante module.mounts (la carpeta de uploads está montada dos veces: una para el procesamiento de imágenes, otra como /wp-content/uploads/ para que las direcciones antiguas de las imágenes sigan funcionando).
  • Shortcodes – pequeñas plantillas que llamas desde Markdown, p. ej. para un vídeo o un cuadro de aviso.
  • Render hooks – tu propia plantilla para cada enlace, imagen o título que genera Markdown.
  • Output formats – el mismo contenido como HTML, RSS, JSON o cualquier otra cosa.
  • Herramientas después del build – el build es solo una carpeta, así que cualquier programa puede trabajar sobre ella. Aquí, imgattrs.py añade srcset y lazy loading a las imágenes de los artículos antiguos, y Pagefind construye el índice de búsqueda.

Lo que te llevas: la mayoría de los plugins resolvían problemas que un sitio estático no tiene. El resto se convirtió en una plantilla o un script que puedo leer entero – lo que también significa que nadie más los actualiza por mí.

🔍 Cómo funciona la búsqueda sin servidor

Un buscador parece necesitar un servidor: alguien tiene que buscar las palabras. Pagefind traslada también ese trabajo al build.

  1. En el build, Pagefind lee cada página HTML terminada. Solo indexa la parte marcada con data-pagefind-body (el artículo), para que los menús y las barras laterales no ensucien los resultados, y se salta todo lo marcado con data-pagefind-ignore. Detecta el idioma por el atributo lang y construye un índice por idioma.
  2. El índice está dividido en muchos archivos pequeños bajo /pagefind/ – 18 MB en total para ocho idiomas. Nadie lo descarga entero.
  3. En el navegador, no se carga nada hasta que alguien busca de verdad. Entonces unas pocas líneas de JavaScript importan Pagefind, que solo trae los trozos del índice para las palabras escritas y los fragmentos de las páginas que coinciden, y muestra título y extracto.
import('/pagefind/pagefind.js')
  .then(function (m) { return m.search(term); })
  .then(function (r) { return Promise.all(r.results.slice(0, 8).map(function (x) { return x.data(); })); })

Un efecto secundario que me gusta: el término de búsqueda nunca llega al servidor como query string, así que no acaba en ningún access log. El formulario está oculto a propósito para los navegadores sin JavaScript – un envío normal del formulario habría puesto el término en la URL.

Lo que te llevas: «estático» no significa «sin interacción». Significa que la interacción ocurre en el navegador del lector, con datos preparados de antemano.

✍️ Mi flujo de trabajo para un artículo nuevo

  1. Escribir el archivo Markdown en site/content/en/posts/<slug>.md con el front matter de arriba. Las traducciones reciben el mismo nombre de archivo, la misma translationKey y etiquetas con sufijo de idioma (hugo-de, hugo-fr, …).
  2. Añadir la imagen en site/uploads/YYYY/MM/ – WebP, como mucho 1536 px de ancho, por debajo de 280 KB. Dentro del texto, las imágenes se referencian como /wp-content/uploads/YYYY/MM/name.webp, la dirección que usaba WordPress.
  3. Construir:
tools/build.sh

Ejecuta check_posts.py, luego hugo --gc --minify, luego imgattrs.py, luego Pagefind. Hugo en sí necesita unos diez segundos para todo el sitio.

  1. Publicar:
tools/deploy.sh <host> 10022

rsync sube el build a una carpeta incoming/; después el servidor lo copia en una nueva carpeta de release y cambia un enlace simbólico hacia ella en un solo paso. Las últimas cinco releases se conservan, así que tools/deploy.sh <host> 10022 rollback vuelve atrás en un segundo. La clave de despliegue no puede hacer nada más – el servidor solo acepta exactamente estos comandos para ella.

  1. Hacer commit y push del repositorio de contenido.

Dos repositorios: código abierto, contenido privado

El servidor y las herramientas de build viven en un repositorio público, www_hugo, junto al código de Ansible para todo lo demás. El contenido – artículos, imágenes, plantillas, borradores – vive en uno privado. El motivo es que un repositorio lo recuerda todo: una imagen que retiro se quedaría para siempre en el historial de un repo público, y los borradores no son para los lectores. El servidor solo recibe archivos terminados a través del paso de despliegue y nunca ve un borrador; el repo público no ve el contenido en absoluto.

Lo que te llevas: publicar son dos pasos independientes. El servidor muestra lo último que se desplegó, Git guarda lo último que se commiteó – yo hago las dos cosas, en ese orden.

⬆️ Actualizar Hugo

Hugo no está instalado en el servidor en absoluto. Vive como un único binario en .tools/ en la máquina que construye el sitio, junto con Pagefind. Las versiones están fijadas en el versions.yml del repo público:

hugo_version:                "0.169.0"   # github.com/gohugoio/hugo/releases
pagefind_version:            "1.6.0"     # github.com/Pagefind/pagefind/releases

Una actualización sigue el mismo patrón que en todo lo demás aquí:

  1. Leer las release notes – Hugo marca de vez en cuando funciones de plantilla como obsoletas y avisa de ello en la salida del build mucho antes de eliminarlas.
  2. Descargar la release extended para Linux, comparar su SHA-256 con el archivo de checksums de la release, sustituir .tools/hugo.
  3. Construir en una carpeta aparte y compararla con el build anterior (diff -r). Solo deberían aparecer diferencias esperadas.
  4. Cambiar la versión fijada en versions.yml, desplegar, hacer commit.

Como el servidor solo sirve archivos, una actualización de Hugo nunca puede romper el sitio en marcha. El peor caso es un build que falla o que se ve distinto – y eso pasa en mi máquina, no delante de los lectores.

Lo que te llevas: el generador es una herramienta de build, como un compilador. Fíjalo, actualízalo a propósito y compara la salida.

🤖 Lo que hace Claude en torno a Hugo

La mayor parte del trabajo en este blog la hago junto con Claude (la IA de Anthropic) en el terminal. Desglosado por temas:

  • Migración: exportación desde WordPress, conversión de cada artículo a Markdown con front matter, direcciones antiguas y rutas de imágenes conservadas, redirecciones para los slugs cambiados.
  • Plantillas y aspecto: reconstrucción del antiguo tema en plantillas de Hugo, el slider, la barra lateral, los rincones oscuros como las páginas de archivo por fecha.
  • SEO: el partial head.html, el sitemap con hreflang, los datos estructurados, imágenes de vista previa por debajo del límite de WhatsApp.
  • Escribir y traducir: borradores con mis palabras, traducciones a los ocho idiomas con reglas fijas (bloques de código idénticos byte a byte, enlaces reescritos por idioma) y un comprobador que compara cada traducción con el original en inglés.
  • Comprobaciones: la comprobación del build, una revisión de enlaces sobre todas las páginas generadas, una comprobación en vivo contra el sitio en marcha.
  • Servidor y despliegue: el rol de Ansible para nginx, el despliegue atómico, SELinux, la monitorización.
  • Resolución de problemas: averiguar por qué un artículo no aparecía (ver la siguiente sección) o por qué una ruta de navegación apuntaba a una página inexistente.

Lo que queda en mis manos: decidir qué se escribe y se publica, leer cada borrador, ejecutar los playbooks, y cada push y cada despliegue – Claude pregunta antes de cada uno.

Lo que te llevas: un sitio estático son archivos de texto y pequeños scripts – justo el material que un asistente de IA maneja bien. Las decisiones siguen siendo mías.

🐛 Trampas que solo aparecieron en la operación

  1. Un artículo del futuro no se construye. Puse la fecha de un artículo a las 15:50 y construí a las 15:44 – Hugo lo dejó fuera sin decir nada. Ningún error, el artículo simplemente faltaba. date tiene que estar en el pasado, o el build necesita --buildFuture.
  2. Una página de día que faltaba. La ruta de navegación de un artículo nuevo enlazaba a su archivo del día (/2026/11/13/), que no existía, porque las páginas de fecha son archivos de contenido, no páginas generadas. La revisión de enlaces lo encontró; ahora una fecha nueva necesita su _index.md. Y mientras escribía precisamente este artículo, los dos errores volvieron a ocurrir: el artículo estaba fechado a las 08:30 y se construyó a las 08:22, y su nueva página de día llevaba las 12:00 – una página fechada a mediodía está en el futuro toda la mañana.
  3. El HTML convertido es frágil. Los artículos importados de WordPress son una mezcla de Markdown y HTML en bruto. En algunos, había palabras pegadas o había sobrevivido un ** suelto. Solo una revisión de las páginas renderizadas en todos los idiomas los encontró.
  4. Los ajustes tipográficos importan. El typographer de Hugo convierte -- en una raya por defecto. WordPress no lo hacía, así que comandos como --check se habrían convertido en –check en los artículos antiguos. El ajuste ahora solo toca comillas y apóstrofos.
  5. No todo debe estar en la búsqueda y en los feeds. El aviso legal y la política de privacidad contienen la dirección postal. Son noindex, quedan fuera de los feeds RSS y del índice de Pagefind – un plugin habría necesitado un ajuste para cada una de esas cosas; aquí es una condición en las plantillas.
  6. Algunas direcciones vienen del front matter. Unos pocos artículos antiguos llevan una clave url: con la ruta completa. En las traducciones necesita el prefijo de idioma; si no, todos los idiomas reclaman la misma dirección.

Lo que te llevas: Hugo hace exactamente lo que se le dice y rara vez se queja. Las comprobaciones que los plugins de WordPress hacían en silencio hay que escribirlas – y entonces se ejecutan en cada build.

📊 Medido

Artículos146, en 8 idiomas
Páginas HTML generadasunas 23.000 (artículos, etiquetas, categorías, archivos)
Build de Hugounos 10 s (sitio completo)
Carpeta de salida498 MB, casi todo imágenes
Índice de búsqueda18 MB para 8 idiomas, cargado en trozos pequeños
Software en el servidor para el blognginx

🎯 Las lecciones

  • Decide dónde ocurre el trabajo: en la visita (WordPress) o al publicar (Hugo).
  • Comprueba qué hacía realmente un plugin antes de sustituirlo – la mayor parte es una plantilla, una parte es una comprobación que tienes que escribir tú mismo.
  • La búsqueda, los feeds y los sitemaps funcionan sin servidor cuando el build prepara los datos.
  • Fija el generador como cualquier otra herramienta de build y compara la salida antes de desplegar.
  • Un artículo que falta sin mensaje de error suele ser una fecha en el futuro.
  • Mantén contenido y código separados cuando el código es público.
Parte de los textos e imágenes de este sitio está asistida o generada por IA. Detalles