theme: local images broken in 5.26.0

[cagix]

Just to let you know, it seems, that local images are broken in Relearn 5.26.0 / Hugo v0.123.8 in combination with "ugly url".

MWE:

File _index.md with just this content:

## Kursformat

![](bar.png?width=80%25&height=auto)

Image bar.png living in the same folder as _index.md ...

Using Hugo:

canonifyURLs: true   # prepend all relative URLs w/ baseURL
relativeURLs: false  # do NOT rewrite relative URLs to be relative to current content
uglyurls: true       # use foo.de/bar.html instead of foo.de/bar/ (our new ILIAS 7.x HTML-Lernmodul won't find landing pages else)

languageCode: "de-DE"
metaDataFormat: "yaml"

theme:
  - "hugo-theme-relearn"

This will yield an empty box:

This used to work before, however I cannot say for sure if this is from the last Relearn update or earlier.

[McShelby]

At the moment I only can confirm this. After a day of WTF moments in #804 I probably need a break...

Update: It worked with the exampleSite of the theme in this configuration. The reason I first confirmed it was due to the reason that I used the built-in figure shortcode. This one seems to have limitations. This happened with Hugo 0.123.8.

Anozher update: Five hours ago Hugo 0.124.0 fixed this in its shortcode. So everything works for me.

@cagix: Could you give me access to your MWE?

Anyways, thanks for reporting.

[McShelby]

In your repo you are using this on the specific page:

![](admin/images/ki_fahrplan_2023-2024.png){width="80%"}

Also I don't see any index.md or _index.md files, which means you are not using any page bundles. Hugo is quite limiting to the locations where so called resources can live.

It might work, if not following Hugo's requirements but in my experience this is a bad idea as it will fire back at some future point in time.

So in your case it might be a Hugo "issue", so try to revert back to 0.122.0 to see if this changes anything.

[cagix]

In your repo you are using this on the specific page:

![](admin/images/ki_fahrplan_2023-2024.png){width="80%"}

oh, you found my repo 🙃

indeed, the structure i'm using here is intended to be read by humans (via gh-preview), and is definitely not hugo compatible.

to produce the website, i do a little preprocessing. during this step all readme.me files will be renamed into _index.md. also there is quite a lot of movement of files and images, and the intermediate result should be feasible from hugos point of view. e.g., the toplevel readme.me will be renamed to _index.md, the images referred to in this file will be moved to the same folder and all links in this file to images and markdown files will be adapted accordingly. so just before the hugo step the situation is as described in the first comment above.

i've seen the hugo update yesterday after my posting, and will give it a try tomorrow. if this does not resolve my issue, i'll prepare a proper mwe and give you access.

So in your case it might be a Hugo "issue", so try to revert back to 0.122.0 to see if this changes anything.

thx for this advice, will give it a try.

[cagix]

@McShelby Unfortunately, even after updating to Hugo v0.124.0 and Relearn v5.26.1, the issue is still the very same. I have tried it locally and on our LMS.

As promised, here is an MWE: https://github.com/Programmiermethoden-CampusMinden/mwe-hugorelearn (you should have write access)

The href of the images (i.e. the outer a element) seems to be simply wrong, whereas the src path in the enclosed img element is fine invalid, too:

<a href="#R-image-e6da6145af2b42742fdd08ac9c5f43fe" class="lightbox-link">
    <img class="noborder lazy lightbox noshadow figure-image" loading="lazy" src="file://PATH/mwe/docs/PATH/mwe/docs/ki_fahrplan_2023-2024.png?width=80%25&height=auto" style=" height: auto; width: 80%;">
</a>

(formatted manually to improve readability)

Edit: ARGH. I've just realised that the local path actually appears twice in the img: PATH/mwe/docs?! (using baseURL: "file://PATH/mwe/docs/" here)

Edit: Can confirm, that this also happens for a baseURL pointing to a webserver:

<a href="#R-image-ea63cd67d65e6ede4b453c9c0fc0b371" class="lightbox-link">
    <img class="noborder lazy lightbox noshadow figure-image" loading="lazy" src="https://www.hsbi.de/elearning/data/FH-Bielefeld/lm_data/lm_1358898/elearning/data/FH-Bielefeld/lm_data/lm_1358898/ki_fahrplan_2023-2024.png?width=80%25&height=auto" style=" height: auto; width: 80%;">
</a>

You can see, the part elearning/data/FH-Bielefeld/lm_data/lm_1358898 appears twice. However, this is only a part of the baseURL (using baseURL: "https://www.hsbi.de/elearning/data/FH-Bielefeld/lm_data/lm_1358898/" here).

[cagix]

So in your case it might be a Hugo "issue", so try to revert back to 0.122.0 to see if this changes anything.

thx for this advice, will give it a try.

Can confirm, with Hugo v0.122.0 and Relearn v5.26.1 everything works as expected.

[cagix]

@McShelby Would you agree that this is a Hugo problem? Should I open a new issue in the Hugo repo?

[McShelby]

Let me first take a look into it (will most likly happen this evening) before you post an error for Hugo. I know there was a change regarding how links are anchored and I first have to take a look into it myself.

From my guts I still think it's a configuration isssue with your site but we'll see if this is really the case.

[McShelby]

From my first look into the repo I noticed canonifyURLs. Hugo's jmooring is flagging this as deprecated so I removed it from all my configurations. If you remove this, does it work then?

[cagix]

@McShelby I have been experimenting with my Hugo configuration just now.

The culprit is clearly canonifyURLs: true. If I deactivate this option completely (i.e. deleting it from the config file), the paths are correct now (albeit being now relative paths instead of absolute paths on the server).

I'm not sure why I activated this option in the first place. If my memory serves me right, I had to use uglyurls: true after the upgrade of our ILIAS to v7.x, because a path foo.de/bar/ was answered by the server with a 404 and I needed foo.de/bar.html instead (hence uglyurls: true). And I seem to remember experimenting a little further back then and also needing canonifyURLs: true plus relativeURLs: false. But when I try this today on the ILIAS server, uglyurls: true seems to be the only really necessary setting.

That being said, I find it disturbing that Hugo is constantly making API changes and deprecating things - and in this case not even issuing a warning.

[McShelby]

Previously in the theme docs, I recommended canonifyURLs=true asweill, as there were some oddities in older Hugo version (that I can't remember anymore).

Now that the theme only supports Hugo 0.112.4 or higher, this does not seem to be necessary anymore.

[McShelby]

Btw: I recently updated the section for usage scenarios in the docs.

[cagix]

Btw: I recently updated the section for usage scenarios in the docs.

thx! reading the warning regarding webserver + subdirectory, maybe this was the reason for me using relativeURLs: false. hmm.

---

edit: @McShelby your info in the link above regarding uglyURL and appending an additional index.html to all page links seems to be valid only for links in the menu:

• using uglyURL: false:
  • menu: BASE/intro/intro-ai/index.html
  • link in page: BASE/intro/intro-ai/ <= no appended extra index.html
• using uglyURL: true (not really relevant here, but for sake of completeness):
  • menu: BASE/intro/intro-ai.html
  • link in page: BASE/intro/intro-ai.html

it would be great, if in the uglyURL: false case all page links would get automatically an extra index.html, because this would allow me to drop this ugly uglyURL business :)

[McShelby]

it would be great, if in the uglyURL: false case all page links would get automatically an extra index.html

It should. If not, it's either a bug or the page/resource was not found by link resolution. You can check if resultion was successful by adding

[params]
link.errorlevel = "warning"
image.errorlevel = "warning"

[cagix]

wow. interesting. now hugo is yelling at me:

Error: error building site: render: failed to render pages: render of "home" failed: "/usr/local/share/pandoc/hugo/hugo-theme-relearn/layouts/_default/index.html:1:4": execute of template failed: template: _default/index.html:1:4: executing "_default/index.html" at <partial "_main.hugo" .>: error calling partial: "/usr/local/share/pandoc/hugo/hugo-theme-relearn/layouts/partials/_main.hugo:7:103": execute of template failed: template: partials/_main.hugo:7:103: executing "partials/_main.hugo" at <partial "output-partial.hugo" (dict "base" "content" "page" . "parameter" . "outputFormat" $outputFormat)>: error calling partial: "/usr/local/share/pandoc/hugo/hugo-theme-relearn/layouts/partials/output-partial.hugo:13:8": execute of template failed: template: partials/output-partial.hugo:13:8: executing "partials/output-partial.hugo" at <partial (printf "%s.%s" $base $suffix) $parameter>: error calling partial: "/usr/local/share/pandoc/hugo/hugo-theme-relearn/layouts/partials/content.html:1:4": execute of template failed: template: partials/content.html:1:4: executing "partials/content.html" at <.Content>: error calling Content: "/pandoc/temp/_index.md:115:1": failed to render shortcode "tabs": "/pandoc/temp/_index.md:1:1": failed to render shortcode "tab": execute of template failed: template: _default/_markup/render-link.html:1:4: executing "_default/_markup/render-link.html" at <partial "shortcodes/link.html" (dict "page" .Page "url" .Destination "title" .Title "content" .Text)>: error calling partial: "/usr/local/share/pandoc/hugo/hugo-theme-relearn/layouts/partials/shortcodes/link.html:69:19": execute of template failed: template: partials/shortcodes/link.html:69:19: executing "partials/shortcodes/link.html" at <$page.Site.Params.link.errorlevel>: can't evaluate field errorlevel in type []interface {}

but if i understand this output correctly, it complains about a tab shortcode (which is working just fine), and all page links ala [Einführung KI]({{% relref "intro-ai" %}}) are coming only after this shortcode?

but this error aside - maybe the theme does not resolve this link properly because i'm relying on the hugo magic to resolve a resource by name - in this case it should (and will) find this file: intro/intro-ai/_index.md.

[McShelby]

The error might come that this was TOML syntax not YAML syntax?

[cagix]

uhm, i translated this into

params:
  link:
  - errorlevel: "warning"
  image:
  - errorlevel: "warning"

[cagix]

🙈 that would do w/o the dashes ...

so, now it's more regarding links:

hugo --config hugo.yaml,local.yaml  --themesDir "/usr/local/share/pandoc/hugo"  --contentDir temp  --destination docs  --printPathWarnings --panicOnWarning
Start building sites … 
hugo v0.124.0-629f84e8edfb0b1b743c3942cd039da1d99812b0 linux/arm64 BuildDate=2024-03-16T15:44:32Z VendorInfo=gohugoio

WARN  "/pandoc/temp/_index.md": link 'BASE/admin/exams-hsbi/' is not a page but linked anyways
WARN  "/pandoc/temp/_index.md": link 'BASE/admin/exams-tdu/' is not a page but linked anyways
Total in 359 ms
Error: error building site: render: failed to render pages: render of "home" failed: "/usr/local/share/pandoc/hugo/hugo-theme-relearn/layouts/_default/index.html:1:4": execute of template failed: template: _default/index.html:1:4: executing "_default/index.html" at <partial "_main.hugo" .>: error calling partial: "/usr/local/share/pandoc/hugo/hugo-theme-relearn/layouts/partials/_main.hugo:7:103": execute of template failed: template: partials/_main.hugo:7:103: executing "partials/_main.hugo" at <partial "output-partial.hugo" (dict "base" "content" "page" . "parameter" . "outputFormat" $outputFormat)>: error calling partial: "/usr/local/share/pandoc/hugo/hugo-theme-relearn/layouts/partials/output-partial.hugo:13:8": execute of template failed: template: partials/output-partial.hugo:13:8: executing "partials/output-partial.hugo" at <partial (printf "%s.%s" $base $suffix) $parameter>: error calling partial: "/usr/local/share/pandoc/hugo/hugo-theme-relearn/layouts/partials/content.html:1:4": execute of template failed: template: partials/content.html:1:4: executing "partials/content.html" at <.Content>: error calling Content: "/pandoc/temp/_index.md:115:1": failed to render shortcode "tabs": "/pandoc/temp/_index.md:1:1": failed to render shortcode "tab": execute of template failed: template: _default/_markup/render-link.html:1:4: executing "_default/_markup/render-link.html" at <partial "shortcodes/link.html" (dict "page" .Page "url" .Destination "title" .Title "content" .Text)>: error calling partial: "/usr/local/share/pandoc/hugo/hugo-theme-relearn/layouts/partials/shortcodes/link.html:70:10": execute of template failed: template: partials/shortcodes/link.html:70:10: executing "partials/shortcodes/link.html" at <warnf "%q: link '%s' is not a page but linked anyways" $page.File.Filename $url>: error calling warnf: "/pandoc/temp/_index.md": link 'BASE/admin/exams-tdu/' is not a page but linked anyways

strangely, there is a page admin/exams-hsbi/_index.md, as well as admin/exams-tdu/_index.md. the links used in the _index.md are [Prüfungsvorbereitung HSBI]({{% relref "exams-hsbi" %}}) and [Prüfung & Noten @TDU]({{% relref "exams-tdu" %}}).

edit: also in admin/ there is a page _index.md to get a proper bundle.

[McShelby]

Hugo can be - ehh - quite challenging (to say politely).

I recommend getting rid of the relref calls completly (can be done by a regex). This is not required anymore and if I remember correctly is even discouraged by jmooring.

This may lead to other issues as I think using "the hugo magic to resolve a resource by name" will not work with plain markdown links.

The reason your build fails is due to your configuration to treat warnings as errors (which I generally find a good thing). To fix all those link issues it is helpful to deactivate this behavior until all links are fixed.

[cagix]

Hugo can be - ehh - quite challenging (to say politely).

🤣

I recommend getting rid of the relref calls completly (can be done by a regex). This is not required anymore and if I remember correctly is even discouraged by jmooring.

Unfortunately, in my workflow there is currently no viable alternative, as my pre-processing step moves and renames files (a lot) to be compliant w/ Hugo. It would be serious overhead to calculate and track all the new paths, that's why I'm relying on Hugo's magic here :)

But maybe I should tackle this problem and expand my pre-processing. Alas, life is short and so is time :)

[cagix]

The reason your build fails is due to your configuration to treat warnings as errors (which I generally find a good thing). To fix all those link issues it is helpful to deactivate this behavior until all links are fixed.

yeah, i thought, we are tracking down, why the relearn theme does not append an _index.md to all page links?

[McShelby]

Sure, but if the build fails with the first warning, it may be a bit time consuming as the list of warnings may not be complete for the whole site. So you would need to fix each link and restart the build afterwards until Hugo finally runs without failure. Quite time consuming.

[McShelby]

To sum it up:

• your initial issue was solved by removing uglyURLs from the config
• the upcoming issue that no index.html is appended to some links is still unresolved

For the second point, the best would be to have an repository in the form right before Hugo runs thru it. I don't care about superflous files. The closer it is to your real environment, the better for me to test.

[cagix]

To sum it up:

• your initial issue was solved by removing uglyURLs from the config

✅ (actually, that is removing canonifyURLs, but keeping uglyURLs)

• the upcoming issue that no index.html is appended to some links is still unresolved

For the second point, the best would be to have an repository in the form right before Hugo runs thru it. I don't care about superflous files. The closer it is to your real environment, the better for me to test.

I've upgraded my MWE to be a real live example. Please find it here: https://github.com/Programmiermethoden-CampusMinden/mwe-hugorelearn

You will find the files from https://github.com/Artificial-Intelligence-HSBI-TDU/KI-Vorlesung after the pre-processing step, i.e. this is actually the input presented to Hugo.

If you run Hugo on the project, you will find, that with uglyURLs: false there will be an _index.md appended to all links in the menu, but not to links e.g. in the "Fahrplan" table in the main page itself. Look for example at "Fahrplan > Woche 41 > Problemlösen" vs. "Menu > Einführung KI > Problemlösen".

[McShelby]

Okay, I found the reason for this behavior but am not sure what to do next.

So first: There is no bug neither in the theme nor in Hugo. It works correct in terms of its limitations.

If you are using ref/relref Hugo resolves those links to URLs. Because you have defined a baseURL that points to a subdirectory of the server root, this subdirectory is prepended before the theme's render hook gets it.

The render hook tries to resolve this to a page but fails, because the lookup is only allowed for the so called path which basically is the URL without the subdirectory part.

When the lookup fails, two things happen:

• if configured, the theme warns about it
• the URL is left unchanged (and no index.html is appended) because the theme is not allowed to make any assumption about links outside of Hugo.

So the main question is: Are you dependend on the appended index.html? Usually this is not the case if pages are served by a webserver.

[cagix]

@McShelby thx for your detailed analysis 🙏

So the main question is: Are you dependend on the appended index.html? Usually this is not the case if pages are served by a webserver.

our ilias cannot handle non-ugly urls, i.e. i depend on the appended _index.md ... perhaps this is a limitation of ilias, maybe it is just a matter of configuration. however, i'm in no position to change either ...

so i guess, i'm stuck to uglyurl, then. this works with our ilias system as well as from a local file system.

from my point of view this issue can be closed.

thx again for your time and your amazing work 👌

[McShelby]

Thanks for using the theme!