Cómo usar Hugo aliases: redirecciones de URL antiguas y guía para corregir 404

Los aliases de Hugo sirven para crear redirecciones desde URL antiguas de una página.

Cuando cambias la URL de un artículo, fusionas páginas, migras un blog o quieres corregir una URL incorrecta frecuente, puedes añadir aliases en el Front Matter del artículo. Hugo genera páginas de redirección para esas direcciones antiguas y lleva a los visitantes a la página actual, evitando errores 404 innecesarios.

Para qué sirven los aliases

Hay tres escenarios comunes.

El primero es optimizar las URL de artículos.

Por ejemplo, la URL antigua de un artículo podría ser:

1

/posts/tech/2023-01-01-hello/

Después quizá quieras acortarla a:

1

/hello/

En ese caso, añade la URL antigua como alias en la nueva página. Los buscadores, referencias externas y enlaces sociales antiguos seguirán llegando al contenido.

El segundo escenario es fusionar o migrar páginas.

Si combinas varios artículos antiguos en uno nuevo, o migras desde Hexo, Typecho, WordPress u otra plataforma a Hugo, la estructura de URL antigua suele ser distinta a la del nuevo sitio. aliases permite apuntar esas direcciones antiguas una por una a las páginas nuevas y reducir los 404 tras la migración.

El tercer escenario es corregir errores de escritura.

Algunas URL pueden haberse escrito mal, o sitios externos pueden haber enlazado a una ruta incorrecta. Si ese enlace incorrecto recibe tráfico, puedes crear un alias específico para guiar a los usuarios a la página correcta.

Sintaxis básica

Solo tienes que añadir el campo aliases en el Front Matter del artículo.

Ejemplo en YAML:

1
2
3
4
5
6
7
8


---
title: "Nuevo título del artículo"
date: 2026-05-17T12:00:00+09:00
url: /new-path/my-new-article/
aliases:
  - /old-path/old-article/
  - ../old-version/
---

Aquí /old-path/old-article/ es una ruta relativa al sitio. ../old-version/ es una ruta relativa a la página actual.

En la práctica, suele ser mejor usar rutas relativas al sitio, es decir, rutas que empiezan con /. Son más claras y menos propensas a confusión si cambia la estructura de directorios del artículo.

Relación con el campo url

url define la nueva dirección de la página actual.

aliases define qué direcciones antiguas redirigen a esa nueva dirección.

Por ejemplo:

1
2
3


url: /new-path/my-new-article/
aliases:
  - /old-path/old-article/

Después de compilar el sitio, quien visite /old-path/old-article/ será redirigido a /new-path/my-new-article/.

Si el artículo no define url explícitamente, Hugo genera la dirección de la página actual según la configuración de permalinks, la fecha, el slug y otras reglas del sitio. aliases seguirá apuntando a esa página final generada.

Cómo implementa Hugo las redirecciones por defecto

Por defecto, Hugo genera un archivo HTML independiente para cada alias.

Ese archivo HTML normalmente usa:

1

<meta http-equiv="refresh">

Esto hace que el navegador redirija automáticamente desde la dirección antigua a la nueva.

Este método es simple, portable y funciona bien en hosting estático común. Pero en esencia es una redirección del lado del navegador, no una redirección 301 / 302 devuelta por el servidor.

Para sitios pequeños, esto suele ser suficiente. Mientras la dirección antigua se abra y termine llegando al nuevo artículo, se evitan problemas visibles de 404.

Cuándo considerar redirecciones del servidor

Si el sitio está desplegado en Netlify, Cloudflare Pages, Vercel u otra plataforma que soporte reglas de redirección, conviene considerar redirecciones del servidor.

Las redirecciones del servidor tienen varias ventajas:

Responden de forma más directa, sin devolver primero una página HTML intermedia.
Permiten usar con más claridad códigos 301 o 302.
Centralizan grandes conjuntos de reglas de migración para revisión y mantenimiento.
Dan más control sobre migraciones SEO.

Un enfoque común es desactivar la generación predeterminada de páginas alias de Hugo y generar en su lugar el archivo de reglas que necesita la plataforma. Netlify suele usar _redirects; Cloudflare Pages puede usar _redirects o reglas propias de la plataforma.

Si eliges esta ruta, revisa disableAliases y los custom output formats de Hugo. No elimines simplemente aliases, porque entonces los enlaces antiguos pasarán a ser 404.

Precauciones al usar aliases

Primero, no uses aliases como excusa para cambiar URL sin cuidado.

Cuando una URL se publica, entra en buscadores, RSS, redes sociales, marcadores y referencias externas. Cambiar URL con frecuencia crea coste de mantenimiento. aliases encaja mejor para reparar problemas históricos que para fomentar cambios constantes de ruta.

Segundo, evita bucles de redirección.

Las direcciones antiguas deben apuntar a la nueva dirección de la página actual. No hagas que A redirija a B y B vuelva a A, ni permitas que varias páginas reclamen el mismo alias.

Tercero, cuidado con los prefijos de idioma en sitios multilingües.

Los sitios multilingües de Hugo suelen manejar rutas de idioma automáticamente. Si escribes un alias dentro de una versión de idioma, a veces no necesitas añadir manualmente prefijos como /en/ o /zh-tw/. Si lo haces, puedes generar rutas duplicadas como /en/en/.... Verifica siempre el resultado de la compilación local.

Cuarto, revisa el directorio generado después del cambio.

Tras añadir un alias, compila el sitio y comprueba si aparece el index.html correspondiente a la ruta antigua dentro de public. También confirma que el destino de la redirección dentro de ese archivo es correcto.

Un flujo práctico de comprobación

Después de editar el Front Matter del artículo:

Confirma la nueva URL del artículo actual.
Añade la URL antigua en aliases.
Ejecuta una compilación de Hugo.
Comprueba si public contiene el index.html de la URL antigua.
Abre el HTML generado y confirma que redirige a la nueva URL.
En páginas multilingües, revisa especialmente que no haya prefijos de idioma duplicados.

Este flujo detecta la mayoría de problemas de rutas antes del despliegue.

Resumen

aliases es la herramienta ligera de Hugo para conservar enlaces antiguos.

Es especialmente útil al cambiar URL de artículos, migrar blogs, fusionar páginas y reparar rutas incorrectas. Los sitios estáticos comunes pueden usar directamente las páginas HTML de redirección generadas por Hugo. Los sitios más grandes, o aquellos con requisitos SEO más estrictos, pueden pasar a reglas de redirección del servidor.

La clave no es solo que las URL nuevas se vean mejor. También hay que cuidar las URL antiguas que ya existen. Un sitio que lleva las URL antiguas de forma estable a las páginas nuevas tiene menos riesgo de perder tráfico histórico durante migraciones y rediseños.