Hugo on KnightLi Blog

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

Sun, 17 May 2026 20:00:17 +0800

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:

/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:

---
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.

Referencias

Uso de las habilidades de los agentes de IA para mantener un blog multilingüe de Hugo

Mon, 06 Apr 2026 10:00:00 +0800

Si mantiene un blog multilingüe de Hugo, probablemente se encuentre con un problema frecuente:

Después de terminar el contenido en chino, aún necesitarás las versiones sincronizadas en inglés y chino tradicional.
Todos los archivos de idioma deben mantener la misma estructura.
La portada debe traducirse respetando las reglas del formato Hugo.

sync-post-translations está diseñado exactamente para este escenario.

¿Qué problema resuelve esta habilidad?

El posicionamiento de sync-post-translations es sencillo:

Utilice index.zh-cn.md como archivo fuente
Genere o actualice index.en.md e index.zh-tw.md en el mismo directorio
Mantenga coherente la estructura de Markdown
Aplique reglas explícitas al principio (especialmente “fecha” y “slug”)

Ejemplos de frases desencadenantes:

“Sincronizar traducción al inglés y chino tradicional”
“Traducir esta publicación al inglés y chino tradicional”

Estructura del directorio de habilidades

.\sync-post-translations\
├─ SKILL.md
└─ agents\
   └─ openai.yaml

Código central 1: SKILL.md

A continuación se muestra el archivo de reglas básicas de esta habilidad:

---
name: sync-post-translations
description: 将 Hugo 文章从简体中文源文件（`index.zh-cn.md`）同步翻译为英文（`index.en.md`）和繁体中文（`index.zh-tw.md`）。当用户提出“en 繁体”“同步翻译英文繁体”或要求同时生成/更新两种语言版本且需保持 front matter 与 Markdown 结构一致时使用。
---

# 同步文章翻译

使用此技能为同一篇文章生成或更新多语言版本。

## 工作流程

1. 在目标文章目录中定位源文件 `index.zh-cn.md`。
2. 读取完整 front matter 与正文内容。
3. 在同目录创建或更新 `index.en.md` 与 `index.zh-tw.md`。
4. 确保三语结构对齐后执行 Hugo 构建检查。

## 翻译规则

1. 严格保留 `slug` 原值。
2. `date` 统一规范为 Hugo 常用带时间格式（RFC3339），示例：`2026-04-05T10:00:00+08:00`。
3. 自然翻译以下 front matter 字段：`title`、`description`、`tags`、`categories`。
4. 保持 Markdown 结构不变：标题层级、列表形态、代码块、链接与命令行示例。
5. 技术标识符保持原样：文件名、CLI 参数、模型名、设备名、URL、包名等。
6. 若 YAML 的 `title` 含有 `:`，必须加引号，避免解析报错。
7. 在不改变语义前提下，使用目标语言自然标点与表达习惯（`en`、`zh-tw`）。

## 输出约定

1. 仅在源文章同目录写入目标文件。
2. 汇报变更的文件路径。
3. 条件允许时执行 `hugo --source . --destination public`，并反馈通过/失败；失败时给出关键报错行。

## 质量标准

1. 全文术语前后一致。
2. 避免机器直译感，优先可发布文风。
3. 章节内容完整，不省略示例、注意点与总结。

Código central 2: agentes/openai.yaml

Este archivo define cómo se presenta y solicita la habilidad en el lado del agente:

interface:
  display_name: "同步文章翻译"
  short_description: "生成或更新 EN + ZH-TW 翻译稿"
  default_prompt: "使用该技能在同一 Hugo 文章目录中，从 `index.zh-cn.md` 生成或同步 `index.en.md` 与 `index.zh-tw.md`，保留 `date` 与 `slug`，保持 Markdown 结构一致，并执行 Hugo 构建校验。"

Ejemplo de uso práctico

1) Activador del lenguaje natural

1
2

请把 content/post/2026/04/06/index.zh-cn.md 同步翻译成英文和繁体，
要求 date 用 RFC3339，slug 不变，最后跑 hugo 校验。

2) Resultado esperado

已更新：
- content/post/2026/04/06/index.en.md
- content/post/2026/04/06/index.zh-tw.md

构建校验：
- hugo --source . --destination public
- 结果：PASS

Por qué son importantes estas reglas

Mantener “slug” sin cambios conserva las URL estables y los vínculos de retroceso históricos.
Normalizar la “fecha” a RFC3339 con zona horaria evita la ambigüedad en el análisis de Hugo/tema.
Mantener la estructura de Markdown sin cambios evita problemas de representación de TOC, bloques de código y códigos cortos.
No traducir identificadores técnicos reduce significativamente las discrepancias entre archivos y comandos rotos.

Errores comunes y cómo evitarlos

Si title contiene : sin comillas, el análisis de YAML puede fallar.
Traducir --flags, URL o nombres de paquetes interrumpirá los ejemplos de comandos.
Si los niveles de encabezado difieren entre idiomas (por ejemplo, ## se convierte en ###), los anclajes pueden volverse inconsistentes.
Traducir solo el contenido del cuerpo, pero no el texto inicial, puede romper las páginas de la lista y los metadatos de SEO.

Práctica de Hugo Shortcode: paquete-archivo (mantenga archivos y archivos adjuntos multilingües en un paquete de una página)

Sun, 29 Mar 2026 00:00:00 +0000

En sitios multilingües, las publicaciones suelen compartir los mismos archivos adjuntos (por ejemplo, PDF, archivos de configuración o scripts). Si cada versión de idioma mantiene enlaces de descarga manualmente, la pérdida de enlaces y los archivos perdidos se vuelven comunes con el tiempo.

Este artículo presenta un código corto de Hugo reutilizable, “bundle-file”, para resolver este problema.

Objetivo

Mantenga los archivos de publicaciones y archivos adjuntos multilingües en el mismo directorio del paquete de páginas, por ejemplo:

content/post/2026/03/09/01/
  index.zh-cn.md
  index.zh-tw.md
  index.en.md
  demo.pdf
  script.sh

Esto maximiza la reutilización y evita copias duplicadas. Después de que Hugo cree páginas HTML, todas las versiones de idiomas deben apuntar al mismo archivo adjunto en lugar de archivos duplicados.

Implementación de código corto

Archivo: layouts/shortcodes/bundle-file.html

{{- $name := .Get "name" -}}
{{- $text := .Get "text" | default $name -}}

{{- $res := .Page.Resources.GetMatch $name -}}
{{- if not $res -}}
  {{- range .Page.AllTranslations -}}
    {{- if not $res -}}
      {{- $tmp := .Resources.GetMatch $name -}}
      {{- if $tmp }}{{ $res = $tmp }}{{ end -}}
    {{- end -}}
  {{- end -}}
{{- end -}}

{{- if $res -}}
<a href="{{ $res.RelPermalink }}">{{ $text }}</a>
{{- else -}}
<span>Missing file: {{ $name }}</span>
{{- end -}}

bundle-file funciona con una estrategia simple:

Primero busque el archivo en los recursos de la página actual.
Si no lo encuentra, busque el mismo nombre de archivo en otras páginas traducidas.
Genere un enlace de descarga cuando lo encuentre o muestre un mensaje de archivo faltante cuando no lo encuentre.

Parámetros

name: nombre del archivo adjunto (obligatorio)
text: etiqueta del enlace (opcional); por defecto es nombre

Ejemplo de uso

`1`	`Missing file: demo.pdf`

Sin “texto”:

`1`	`Missing file: demo.pdf`

Lista de verificación previa a la publicación

Coloque archivos adjuntos y publicaciones en el mismo paquete de páginas.
Asegúrese de que “nombre” coincida exactamente con el nombre de archivo real (incluido el caso).
Haga clic en los enlaces en la vista previa local para confirmar la accesibilidad.

Resumen

bundle-file convierte el manejo de archivos adjuntos multilingües del mantenimiento manual de rutas a una búsqueda automática basada en reglas. Para bases de conocimientos y blogs técnicos de larga duración, esto reduce el riesgo de enlaces rotos y el tiempo de revisión previa al lanzamiento.