Link Resolution Errors on Sites using Subdirectory - Possible Bug?

[russfeld]

Hi Sören - great work as always! Your theme is amazing and powers a lot of our work developing online textbooks for our students.

I'm updating my fork to the latest version, and I may have encountered a bug (or an unhandled edge case) with the new local page link resolution.

A quick sample site to demonstrate the issue: https://github.com/russfeld/hugo-test

The site is configured to be served at a subdirectory using baseURL = "https://example.com/subdir/" and relativeURLS = "false" in the hugo.toml config file.

On the homepage, I include links to a branch bundle branch and a leaf bundle leaf using direct links, the ref shortcode, and the relref shortcode.

Branch Bundles

[Link to Branch](branch)

REF Shortcode to Branch: {{% ref "branch" %}}

[REF Link to Branch]({{% ref "branch" %}})

RELREF Shortcode to Branch: {{% relref "branch" %}}

[RELREF Link to Branch]({{% relref "branch" %}})

---

Leaf Bundles

[Link to Leaf](leaf)

REF Shortcode to Leaf: {{% ref "leaf" %}}

[REF Link to Leaf]({{% ref "leaf" %}})

RELREF Shortcode to Leaf: {{% relref "leaf" %}}

[RELREF Link to Leaf]({{% relref "leaf" %}})

On the website, these render correctly and all go to the correct page:

However, when building the site, I get some warnings from those RELREF links (but not the REF links since they are absolute):

❯ hugo serve
Watching for changes in /home/russfeld/web/hugo-test/content/{branch,leaf}
Watching for config changes in /home/russfeld/web/hugo-test/hugo.toml, /home/russfeld/web/hugo-test/go.mod
Start building sites … 
hugo v0.126.1-3d40aba512931031921463dafc172c0d124437b8+extended linux/amd64 BuildDate=2024-05-15T10:42:34Z VendorInfo=gohugoio

WARN  "/home/russfeld/web/hugo-test/content/_index.md": link '/subdir/branch/' is not a page or a resource but linked anyways
WARN  "/home/russfeld/web/hugo-test/content/_index.md": link '/subdir/leaf/' is not a page or a resource but linked anyways

# output shortened #

Web Server is available at http://localhost:1313/subdir/ (bind address 127.0.0.1)

As I was debugging it, I realized that the subdir path from the baseURL setting was being included in the URL sent to the layouts/partials/shortcodes/link.html partial. I'm not sure where it is getting added (probably somewhere upstream in Hugo itself). Since the shortcode uses that URL to get the path to the file, it ends up looking for pages /subdir/branch and /subdir/leaf and can't find them, even though they are valid links.

I tried a quick fix by overriding that shortcode and adding a bit of code to strip the path from the baseURL out of the page URL and it seems to suppress the errors, but I'm not confident that is truly a fix that works in all use-cases (this is added after line 29 in https://github.com/McShelby/hugo-theme-relearn/blob/64b4ad751ef8922f6fb57c7c4c785bdf345c91f9/layouts/partials/shortcodes/link.html - it looks like you are updating that already in the latest beta but I think this is still unhandled):

    {{- $basePath := strings.TrimRight "/" (urls.Parse $page.Site.BaseURL).Path }}
    {{- if ne $basePath "" }}
      {{- $path = strings.TrimPrefix $basePath $path }}
    {{- end }}

Let me know what you think - I'm happy to put together a PR if this is indeed a bug .

Russ

[McShelby]

Hi Russell, thanks for the kind words. What you are doing in your fork is pretty amazing and I took a lot of inspiration from it (eg. modifiable topbars was a thing made with your use case in mind).

I'll take a look into your example, later.
As it does work for the theme docs in the exampleSite in the GitHub workflow (which uses a subdir), I currently assume it's something special in your example setup. But we'll see...

[russfeld]

Thanks! I saw some of the new configuration options and wondered about where they came from - they seemed to exactly fit what I needed! I was able to use them easily in my update this summer - every year it gets easier and easier to port our few customizations on top of your codebase. Keep up the amazing work! 😄

[McShelby]

If you're in need of further adjustments to the themes code base to make custumization easier for you, feel free to drop an issue here.

[McShelby]

That was an interesting deep dive into Hugo's guts.

Link render hooks are sometimes limited to their use case

This render hook may be unable to resolve destinations created with the ref and
relref shortcodes.

https://discourse.gohugo.io/t/not-able-to-render-images/42948/4

In simple cases where you are using only the path option of the ref/relref shortcode, this can be circumvented by adding your own layouts/shortcodes/relref.html with the following content:

{{- .Get "path" | default (.Get 0) }}

If you also plan to use the additional options lang and outputFormat, you'll have to wait until #850 is implemented.

I am planing to provide overwritten rel/relref shortcodes with the theme that also respect those additional options.

[McShelby]

I was wrong with the above link to rel / relref - this links to the shortcode method. The docs for the built in shortcode is here: https://gohugo.io/content-management/shortcodes/#relref

This does not expose the path and outputFormat option - or at least they aren't documented. So it should be relativly safe to already include the above shown basic implementation of the rel / relref shortcode with the theme before #850 is done.

[russfeld]

Wonderful! Thank you for the prompt and thorough response. That seems to solve my issue. I'll go ahead and override the relref shortcode as shown above for now, and watch for updates to #850 in the future.

[McShelby]

I've implemented this in #864 which will be included in the upcoming 6.1.0 release.

[McShelby]

Please note that I had to switch the name of the setting in #882 due to regression. Now your desired behavior must explicitly be activated in your hugo.toml. See the release notes for further detail