How to Use Hugo aliases: Old URL Redirects and 404 Fix Guide

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

Hugo aliases create redirects for old page URLs.

When you change an article URL, merge pages, migrate a blog, or want to fix a common mistaken URL, you can add aliases in the article’s Front Matter. Hugo generates redirect pages for those old addresses and sends visitors to the current page, avoiding unnecessary 404 errors.

What aliases are useful for

There are three common scenarios.

The first is improving article URLs.

For example, your old article URL might be:

`1`	`/posts/tech/2023-01-01-hello/`

Later you may want to shorten it to:

/hello/

In that case, add the old URL as an alias on the new page. Search engines, external references, and social links can still reach the content.

The second scenario is merging or migrating pages.

If you merge several old posts into a new one, or migrate from Hexo, Typecho, WordPress, or another platform to Hugo, the old URL structure often differs from the new site. aliases can point those old addresses to the new pages one by one and reduce post-migration 404s.

The third scenario is fixing spelling mistakes.

Some URLs may have been written incorrectly, or external sites may already link to the wrong path. If that wrong link receives traffic, you can create a dedicated alias for it and still guide users to the correct page.

Basic syntax

Add an aliases field in the article Front Matter.

YAML example:

---
title: "New Article Title"
date: 2026-05-17T12:00:00+09:00
url: /new-path/my-new-article/
aliases:
  - /old-path/old-article/
  - ../old-version/
---

Here /old-path/old-article/ is a site-relative path. ../old-version/ is relative to the current page.

In practice, site-relative paths that start with / are usually easier to reason about. They are clearer and less likely to break when the article directory structure changes.

Relationship with the url field

url defines the new address of the current page.

aliases defines which old addresses redirect to that new address.

For example:

1
2
3

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

After the site is built, visitors to /old-path/old-article/ will be redirected to /new-path/my-new-article/.

If the article does not explicitly set url, Hugo generates the current page URL from the site’s permalinks configuration, the article date, slug, and other rules. aliases will still point to that final generated page.

How Hugo implements redirects by default

By default, Hugo generates a separate HTML file for each alias.

That HTML file usually uses:

`1`	`<meta http-equiv="refresh">`

This makes the browser automatically redirect from the old address to the new one.

This approach is simple, portable, and works well on ordinary static hosting. But it is a browser-side redirect, not a server-side 301 or 302 redirect.

For small sites, this is often enough. As long as the old address opens and eventually reaches the new article, it avoids obvious 404 problems.

When to consider server-side redirects

If your site is hosted on Netlify, Cloudflare Pages, Vercel, or another platform that supports redirect rules, server-side redirects may be a better option.

Server-side redirects have several advantages:

They respond more directly without returning an intermediate HTML redirect page.
They make it easier to use explicit 301 or 302 status codes.
They centralize large migration rule sets for easier review and maintenance.
They give you more control over SEO migrations.

A common approach is to disable Hugo’s default alias page generation and output the redirect rules required by the hosting platform instead. Netlify commonly uses _redirects; Cloudflare Pages can use _redirects or platform-level rules.

If you choose this route, study Hugo’s disableAliases setting and custom output formats. Do not simply remove aliases, or the old links will turn into 404s.

Things to watch out for

First, do not use aliases as an excuse to change URLs casually.

Once a URL is public, it enters search engines, RSS feeds, social platforms, bookmarks, and external references. Frequent URL changes create maintenance costs. aliases are better for fixing historical problems than for encouraging constant path changes.

Second, avoid redirect loops.

Old addresses should point to the current page’s new address. Do not make A redirect to B while B redirects back to A, and do not let multiple pages claim the same alias.

Third, be careful with language prefixes on multilingual sites.

Hugo multilingual sites often handle language paths automatically. If you write an alias inside a language-specific version, you may not need to manually add prefixes such as /en/ or /zh-tw/. Otherwise, you may generate duplicated paths such as /en/en/.... Always verify the local build result.

Fourth, check the generated output after changes.

After adding an alias, build the site and check whether the old path’s index.html appears under public. Also confirm that the redirect target inside that file is correct.

A practical check workflow

After editing the article Front Matter:

Confirm the current article’s new URL.
Add the old URL to aliases.
Run a Hugo build.
Check whether public contains the old URL’s index.html.
Open the generated HTML and confirm that it redirects to the new URL.
For multilingual pages, check especially for duplicated language prefixes.

This catches most path mistakes before deployment.

Summary

aliases are Hugo’s lightweight tool for preserving old links.

They are best suited for article URL changes, blog migrations, page merges, and incorrect-path fixes. Ordinary static sites can directly use Hugo’s default HTML redirect pages. Larger sites, or sites with stricter SEO migration requirements, can move further toward server-side redirect rules.

The real point is not only making new URLs look cleaner. It is also taking care of old URLs that already exist. A site that smoothly carries old URLs to new pages is much less likely to lose historical traffic during migrations and redesigns.

Static Sites on KnightLi Blog