Aliases are broken


Hugo is not generating the aliases sometimes.

I have:


And on /content/support/

Title: "Support"
Aliases: "/support/creators/

Sometimes it generates the alias, sometimes it doesn’t. If I try to add the 2 pages, I end up having none. Sometimes I only have one, others I have the other one.

Its driving me crazy because I can’t share the site and I don’t really know WHERE the error is (or if it is hugo or if I am doing something wrong).

BUT, if I add a fake alias, such as:

Aliases: ["/support/fakeA/", "/support/fakeB"]


But it doesn’t when I want to redirect pages already created. It keeps bringing _default/single.html with the .md content there.

Some help?

An alias is for when you no longer have content in a specific location, so that if someone goes there, it redirects to the page you’ve specified the alias on.


Ricky, thanks for your input.

So I can’t really use an Alias to redirect content that is there? (how can I work around that, then?

Would it be a good solution to simply write a meta redirect on the body of the content itself? (maybe javascript would be better… thinking out loud)

I was under the impression Aliases worked with or without content on the page ;-(

Solved it by doing this:

On /layouts/_default/single.html

{{ if eq .Params.Type "support" }}
	<meta http-equiv="refresh" content="0;URL=/support/">
{{ end }}

Not pretty. Not configurable from the front-matter at all, but at least works…

If someone has a better solution, I’m all ears ;_’

Hugo creates a folder structure and file for the alias (generate the files with hugo and have a look), so, if there is also content in that spot, I reckon it will create a race condition when building. I suspect that is why it sometimes works and sometimes doesn’t.

I speculate you could make a copy of single.html and refer to it using “layout” in frontmatter.

1 Like

That’s completely what happens :+1: . Here’s what the docs say about aliases:

Aliases are rendered before any content are rendered and therefore will be overwritten by any content with the same location.

I’m not sure if the aliases front matter variable expects a string value or an array. The doc page uses an array, even when there’s just one value.

What happens if you change …

Title: "Support"
Aliases: "/support/creators/"

to …

Title: "Support"
Aliases: ["/support/creators/"]

I always use the array notation (if that’s the proper word) when using aliases, and not the single string kind. So I’m not sure if the latter works. (Although it might work either way.)

@RickCogley is right. And this isn’t just the aliases – we have an issue about tracking this and create some kind of warning when this happens, and we should put a priority on that issue … I think. Because this is a little hard to understand and debug when it happens.

A side note, which I don’t think will help the thread starter, but if you look into how aliases are used in the Hugo docs site:

  • The alias kind is disabled
  • We instead create an output format for the home page that creates a Netlify 301 redirects file:

You should be able to use the same pattern for other web servers (Apache .htaccess etc.)

1 Like


Title: "Support"
Aliases: ["/support/creators/"]

Works too. Kind of. Same deal, to be honest, since the problem appears to be what Rick Wonder Cogley stated. The race is sometimes won, sometimes lost, thus, the aliases work or don’t, depending on the build’s mood.

The problem is that I do have content on those pages, since I am creating a Support FAQ ( and I draw all the content for that FAQ from different .md files (,, etc) which, if I am allowed to say, keep things really, really neat for me and the user.

Yes, I realize that having a single .md file is the standard way to write a faq, and if I went that way, I wouldn’t even need any aliases… but things get a bit crowded in a single .md file when writing a very long doc.

The alternative would be to have different pages, with sections for that faq.

So you could have



But, while that’s also standard, it also gets tricky to browse when looking for an answer for a specific problem.

I made it work with just one file:


That’s it. All the other sections get called from that file.

Anyway, I’m satisfied with the solution, since I got the best of the two worlds. A long faq (any man wants to have a long faq, a manly faq) and the content, living in a single page. My users get to quickly iterate through the faq without jumping back and forth through dozen of different pages, and I get to write the faq in a orderly manner (one topic per .md file, which latter gets called into

Thank you Hugo!