Ref and relref emit page not found when used with page aliases

I have a page that has an alias configured, and I have tested that the alias works. However, when I try to create a link to the page

[some text]({{< ref "/path/to/alias" >}}) 

hugo emits REF_NOT_FOUND as it generates the page containing the ref shortcode. the same thing happens with relref. as I read the documentation the aliases should be generated first, so there should be a file there to find when the ref is parsed in a later page. Is this not supported?

The ref and relref shortcodes require a single parameter: the path to a content document, with or without a file extension, with or without an anchor.

Both shortcodes expect a path to a file within the content directory.

Since aliases are supposed to allow you to move a page, one would think that links to that moved page would continue to work. This behavior means that I have to hunt through and find any internal references and change them at the same time, even though I am adding in an alias.

Aliases allow you to create multiple URLs for a page.

If you want to “move” a page, consider specifying slug or url in front matter.

As I read those front matter params, that would override everything. my hope was that I could support links going to the old location even as I reorganize the site and some content ends up in new locations.

with ikiwiki I would have done this by dropping a file that just contained the line

[[!meta redir="/path/to/new/file"]]

in the old location as I moved the content to the new location. is there a short code that I am not seeing that is similar for hugo?

I would move the content to its new canonical path in the content directory and add an alias to its old URL.

Yes, that’s what I tried to describe doing in my first post. The problem is that all the links to it break.

I think we are not communicating very well.

Let’s say I have an article at content/article/ and I want to move it to content/article/

mv content/article/ content/article/

Now I want to make sure that the content can be reached at the original URL as well as the new URL.


title = 'Bar'
date = 2022-07-11T10:48:41-07:00
draft = false
aliases = ['/article/foo/']

Then use the new content path in the ref or relref shortcode.


title = 'Test'
date = 2022-07-11T10:53:29-07:00
draft = false

{{< relref “/article/” >}}

Yes, we’ve now come full circle, and I think I do understand. It means I have to grep the entire site for all instances of ‘[(rel)]ref "article[/]"’ and change them to bar. For a small site that is reasonable. As it grows bigger, this is more burdensome. That’s why I was hoping the ref would match against the aliases, then I can do just as you describe, and it Just Works. Alternately, some function like ikiwiki’s meta redir is an acceptable solution.