link: make resolution reporting configurable

[cagix]

After upgrading to 5.24.0 I'm getting errors when using relref.

temp is the document root (--contentDir temp). In temp/_index.md there is a line [File A]({{% relref "file-a" %}}). Up to and including 5.23.2 this used to find /file_a.html via /file_a/_index.md.

In 5.24.0 I'm getting errors:

WARN  "/temp/_index.md": no page was found for link '/file-a.html'

Hugo seems to locate the file just fine, but complains that it cannot be found?

When I change the relref to just ref, everything seems to work like before. Am I missing something? I would like to link to files and only want to specify the unique file name (since I don't know the exact path at this point - don't ask ;).

Using Hugo v0.122.0.

Edit: When just using {{% relref "file-a" %}} (i.e. not including this in a Markdown link), this works still fine and evaluates to /file-a.html (as expected).

Edit: It actually works also in a Markdown link, i.e. the relref link will be resolved correctly. But Hugo keeps complaining.

[McShelby]

Kind of a moving target, but this was just posted the minute:

https://discourse.gohugo.io/t/did-relref-semantics-change/48306/8

I have to take al look into it. The themes render hook gets the link somehow from the ref/relref shortcode. There seems to be some resultion that doesn't work well with the render hook (although the render hook is resembling Hugo's standard handling as of verison 0.123.0).

[cagix]

Hmmm, this came up after upgrading the relearn theme (same Hugo version before and after the theme update), so I've been looking for changes in behaviour.

[McShelby]

What I wanted to say is that there are also changes in Hugo on the horizion, that will affect the link resolution.

But I will take a look into it. It was not intended to break former behavior with the version 5.24.0.

[cagix]

Yeah, maybe I've been using this not the intended way ...

[McShelby]

I reproduced it in the theme's exampleSite. This happens only if uglyURLs=true is set and only with Hugo 0.122.0 and below. Hugo 0.123.0 fixes this.

The warning is generated by the theme - not by Hugo.

In the previous version, the code had the same issue but no warning was emitted but the implementation caused other side effects (#748). So with this release, the resolution was aligned to way the upcoming 0.123.0 version of Hugo is doing this.

In both the old and the new implementation, the unresolved link is written as-is into the resulting page as a way to not fail the build.

So while the resolution could not find the page, relref still generated a valid link destination. That's the reason why clicking on the link still sends you to the correct page.

In case of --panicOnWarning this will kill your build. Maybe making the warning optional by a config setting?

[McShelby]

@andi-blafasl This change turns off the console message for unresolved links by default. If you want them back, you have to explicitly set this in your hugo.toml. See the updated release notes.

[cagix]

@McShelby thx for your swift response!

indeed, i have to use uglyurl due to recent changes in my lms (ilias).

to understand this better from a users perspective: the way i'm using this feature is not quite supported/intended by the theme, but hugo makes it work in the end? should i switch to rel instead of relref, given the latter did not emitted warnings? am i due to run into problems later with the looming hugo v0.123?

[McShelby]

The way it works is:

• rel / relref link: rel / relref shortcode( Hugo) -> render_hook (here: theme) -> output.
• plain markdown link: render_hook (here: theme) -> output.

the way i'm using this feature is not quite supported/intended by the theme, but hugo makes it work in the end?

Luckily, the theme does not make any assumptions besides the warning. All magic happens in Hugo's rel/relref shortcode. The warning can be benefitial if your site has a certain layout. This will let you find link errors otherwise unnoted or only discoverable by additional tools, manual testing or pure luck.

So your usage relies on Hugo doing the magic in it's shortcode. A plain markdown link will not do this kind of lookup and most likely will generate a invalid link.

The output results are the same if you delete the theme's render_hook. So: No magic by the theme, here.

am i due to run into problems later with the looming hugo v0.123?

That depends on your usage of the rel/relref shortcode. But from what you are saying, I would expect problems.

[cagix]

oh well, that's sad news. indeed i'm relying on hugos magic in relref to find documents by its unique name. maybe it's time to take a closer look to docsify, which seems to support my document layout out of the box. but it doesn't really come anywhere near your beautiful theme :/

[cagix]

@McShelby happy to report, with v5.24.1 everything is back to normal in my workflow! thx 🙏

[cagix]

@McShelby Hugo v0.123.0 plus Relearn v5.24.1 seems to be working like a charm in my setup - so relref still does it's old magic :)

[McShelby]

Yeah, 0.123.0 came out quicker than I had expected.