Did relref semantics change?

support
1

When upgrading from 0.114 to 0.122+git, I noticed that I had to change relref links from:

{{< relref "../ISO-feasibility-candidates" >}}

to

{{< relref "../ISO-feasibility-candidates/index.md" >}}

I scanned the release notes, but didn’t spot the change. Is it to be expected?

2

Works the same as always for me

3

Your examples work the same way they always have. Tested v0.114.0, v0.122.0, v0.123.0-DEV-639073e4.

4

Reproducer:

  • Clone and build hugo v0.123.0-DEV-21d9057dbfe64f668d5fc6a7f458e0984fbf7e56
  • git clone https://github.com/scientific-python/blog.scientific-python.org
  • cd blog.scientific-python.org
  • git submodule update --init
  • hugo
$ ~/go/bin/hugo
Start building sites …
hugo v0.123.0-DEV-21d9057dbfe64f668d5fc6a7f458e0984fbf7e56 linux/amd64 BuildDate=2024-02-11T20:51:11Z

ERROR [en] REF_NOT_FOUND: Ref "../contribution-phase": "/tmp/blog.scientific-python.org/content/posts/networkx/outreachy2023/internship/index.md:13:179": page not found
ERROR [en] REF_NOT_FOUND: Ref "../internship": "/tmp/blog.scientific-python.org/content/posts/networkx/outreachy2023/contribution-phase/index.md:45:111": page not found
ERROR [en] REF_NOT_FOUND: Ref "../node-ordering-Ti-updating": "/tmp/blog.scientific-python.org/content/posts/networkx/vf2pp/ISO-feasibility-candidates/index.md:14:39": page not found
ERROR [en] REF_NOT_FOUND: Ref "../GSoC-2022": "/tmp/blog.scientific-python.org/content/posts/networkx/vf2pp/node-ordering-Ti-updating/index.md:14:64": page not found
ERROR [en] REF_NOT_FOUND: Ref "../ISO-feasibility-candidates": "/tmp/blog.scientific-python.org/content/posts/networkx/vf2pp/graph-iso-vf2pp/index.md:14:78": page not found

I bisected the change to 7285e74090852b5d52f25e577850fa75f4aa8573 (builds fine with previous commit, 5fd1e7490305570872d3899f5edda950903c5213).

5

Thanks for the reproducible example… much easier that trying to guess!

6

The new behavior may well be consistent, I just wanted to make sure it was introduced on purpose. We can easily modify our site to work again. (Whatever the decision, it would be helpful to document whether ../x is allowed.)

7

I know there was a tough decision somewhere in this area, but something doesn’t look right to me. We can relref ../foo from a regular content page (non bundle), but not from a bundle. I’ll play with a bit more later today, then create a GH issue if needed. Either way I’ll update this topic.

2 Likes
8

The short answer is yes. The longer answer is… longer.

The ref and relref shortcodes call the ref and relref template functions which use the same underlying logic as .Page.GetPage and .Site.GetPage. Beginning with v0.123.0, these functions and methods search for the logical page path, which is a new thing in v0.123.0. You can read about it here:

https://gohugo.io/methods/page/path/

The logical page path is neither a file path nor a URL. It is a logical identifier derived from the file path.

Just like there’s a file tree based on file paths, there is a logical tree based on logical paths. How is that relevant to this topic? Because, when calling the functions and methods referenced above, Hugo v0.123.0 searches the logical tree, not the file tree.

Consider the following file tree:

content/
└── s1/
    ├── p1/
    │   └── index.md  <-- "source"
    └── p2.md         <-- "destination"

If we are traversing the file tree (v0.122.0) from source to destination, the path would be:

../p2.md

Visualizing the same content as a logical tree:

content/
└── s1/
    ├── p1  <-- "source"
    └── p2  <-- "destination"

If we are traversing the logical tree (v0.123.0) from source to destination, the path would be:

p2

The description above excludes some subtle details related to link portability, but for the most part is correct. I’m going to ask @bep to review this for accuracy and/or any nuances we need to be aware of.

3 Likes
9

Thank you for the explanation @jmooring. That is a clear concept we can work with. The relref documentation does not reflect that concept yet; would a PR be helpful?

10

Note that some terminology is still in flux. For example, I just edited my response above to use the word “logical” instead of “canonical”, which hopefully is little to easier to comprehend. I’ll take care of the relative path bit when making some other changes to the docs; it affects a number of pages.

1 Like
11

This topic was automatically closed 2 days after the last reply. New replies are no longer allowed.