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

**URL:** <https://discourse.gohugo.io/t/ref-and-relref-emit-page-not-found-when-used-with-page-aliases/39451>\
**Category:** support\
**Created:** [July 11, 2022, 4:05pm UTC](https://discourse.gohugo.io/t/ref-and-relref-emit-page-not-found-when-used-with-page-aliases/39451 "2022-07-11T16:05:11Z")\
**Posts on this page:** 11\
**Page:** 1

<div class="post-metadata">

**Author:** ![lschierer](https://yyz2.discourse-cdn.com/flex036/user_avatar/discourse.gohugo.io/lschierer/32/16221_2.png) [@lschierer](https://discourse.gohugo.io/u/lschierer)\
**Post date:** [July 11, 2022, 4:05pm UTC](https://discourse.gohugo.io/t/ref-and-relref-emit-page-not-found-when-used-with-page-aliases/39451/1 "2022-07-11T16:05:11Z")

</div>

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

```auto
[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](https://gohugo.io/content-management/urls/) 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?

---

<div class="post-metadata">

**Author:** ![jmooring](https://yyz2.discourse-cdn.com/flex036/user_avatar/discourse.gohugo.io/jmooring/32/4214_2.png) [@jmooring](https://discourse.gohugo.io/u/jmooring)\
**Post date:** [July 11, 2022, 4:54pm UTC](https://discourse.gohugo.io/t/ref-and-relref-emit-page-not-found-when-used-with-page-aliases/39451/2 "2022-07-11T16:54:56Z")

</div>

[https://gohugo.io/content-management/cross-references/#use-ref-and-relref](https://gohugo.io/content-management/cross-references/#use-ref-and-relref)

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

---

<div class="post-metadata">

**Author:** ![lschierer](https://yyz2.discourse-cdn.com/flex036/user_avatar/discourse.gohugo.io/lschierer/32/16221_2.png) [@lschierer](https://discourse.gohugo.io/u/lschierer)\
**Post date:** [July 11, 2022, 4:59pm UTC](https://discourse.gohugo.io/t/ref-and-relref-emit-page-not-found-when-used-with-page-aliases/39451/3 "2022-07-11T16:59:43Z")

</div>

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.

---

<div class="post-metadata">

**Author:** ![jmooring](https://yyz2.discourse-cdn.com/flex036/user_avatar/discourse.gohugo.io/jmooring/32/4214_2.png) [@jmooring](https://discourse.gohugo.io/u/jmooring)\
**Post date:** [July 11, 2022, 5:06pm UTC](https://discourse.gohugo.io/t/ref-and-relref-emit-page-not-found-when-used-with-page-aliases/39451/4 "2022-07-11T17:06:29Z")

</div>

> [@lschierer](#):
>
> aliases are supposed to allow you to move a page

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.

---

<div class="post-metadata">

**Author:** ![lschierer](https://yyz2.discourse-cdn.com/flex036/user_avatar/discourse.gohugo.io/lschierer/32/16221_2.png) [@lschierer](https://discourse.gohugo.io/u/lschierer)\
**Post date:** [July 11, 2022, 5:12pm UTC](https://discourse.gohugo.io/t/ref-and-relref-emit-page-not-found-when-used-with-page-aliases/39451/5 "2022-07-11T17:12:29Z")

</div>

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.

---

<div class="post-metadata">

**Author:** ![lschierer](https://yyz2.discourse-cdn.com/flex036/user_avatar/discourse.gohugo.io/lschierer/32/16221_2.png) [@lschierer](https://discourse.gohugo.io/u/lschierer)\
**Post date:** [July 11, 2022, 5:15pm UTC](https://discourse.gohugo.io/t/ref-and-relref-emit-page-not-found-when-used-with-page-aliases/39451/6 "2022-07-11T17:15:13Z")

</div>

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

```auto
[[!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?

---

<div class="post-metadata">

**Author:** ![jmooring](https://yyz2.discourse-cdn.com/flex036/user_avatar/discourse.gohugo.io/jmooring/32/4214_2.png) [@jmooring](https://discourse.gohugo.io/u/jmooring)\
**Post date:** [July 11, 2022, 5:38pm UTC](https://discourse.gohugo.io/t/ref-and-relref-emit-page-not-found-when-used-with-page-aliases/39451/7 "2022-07-11T17:38:03Z")

</div>

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

---

<div class="post-metadata">

**Author:** ![lschierer](https://yyz2.discourse-cdn.com/flex036/user_avatar/discourse.gohugo.io/lschierer/32/16221_2.png) [@lschierer](https://discourse.gohugo.io/u/lschierer)\
**Post date:** [July 11, 2022, 5:43pm UTC](https://discourse.gohugo.io/t/ref-and-relref-emit-page-not-found-when-used-with-page-aliases/39451/8 "2022-07-11T17:43:34Z")

</div>

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

---

<div class="post-metadata">

**Author:** ![jmooring](https://yyz2.discourse-cdn.com/flex036/user_avatar/discourse.gohugo.io/jmooring/32/4214_2.png) [@jmooring](https://discourse.gohugo.io/u/jmooring)\
**Post date:** [July 11, 2022, 5:53pm UTC](https://discourse.gohugo.io/t/ref-and-relref-emit-page-not-found-when-used-with-page-aliases/39451/9 "2022-07-11T17:53:52Z")

</div>

I think we are not communicating very well.

Let’s say I have an article at `content/article/foo.md` and I want to move it to `content/article/bar.md`

```bash
mv content/article/foo.md content/article/bar.md

```

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

content/article/bar.md

```nohighlight
+++
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.

content/article/test.md

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

```

{{\< relref “/article/bar.md” \>}}

```auto

```

---

<div class="post-metadata">

**Author:** ![lschierer](https://yyz2.discourse-cdn.com/flex036/user_avatar/discourse.gohugo.io/lschierer/32/16221_2.png) [@lschierer](https://discourse.gohugo.io/u/lschierer)\
**Post date:** [July 11, 2022, 6:02pm UTC](https://discourse.gohugo.io/t/ref-and-relref-emit-page-not-found-when-used-with-page-aliases/39451/10 "2022-07-11T18:02:51Z")

</div>

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.

---

<div class="post-metadata">

**Author:** ![raisercostin](https://yyz2.discourse-cdn.com/flex036/user_avatar/discourse.gohugo.io/raisercostin/32/23077_2.png) [@raisercostin](https://discourse.gohugo.io/u/raisercostin)\
**Post date:** [November 2, 2024, 7:26am UTC](https://discourse.gohugo.io/t/ref-and-relref-emit-page-not-found-when-used-with-page-aliases/39451/11 "2024-11-02T07:26:23Z")

</div>

I defined an `aliasref` shortcode that is called like ref {{\< aliasref “/path/to/alias” \>}}

```auto
{{/*
  renames considering defined aliases - https://discourse.gohugo.io/t/ref-and-relref-emit-page-not-found-when-used-with-page-aliases/39451
*/}}
{{- $alias := .Get 0 -}}
{{- $pages := where .Site.Pages "Aliases" "intersect" (slice $alias) -}}
{{- if gt (len $pages) 0 -}}
  {{- $page := index $pages 0 -}}
  {{- $url := $page.RelPermalink -}}
  {{- $url | safeURL -}}
{{- else -}}
  {{- errorf "No page found with alias '%s'" $alias -}}
  {{- range .Site.Pages -}}
    {{- if .Params.aliases -}}
      {{- warnf "Page %s has aliases: %s" .RelPermalink .Params.aliases -}}
    {{- end -}}
  {{- end -}}
  {{- ref . $alias | safeURL -}}
{{- end -}}

```