Invalid image links in 0.123 for baseURL with subdirectory

In my branch bundle is a simple markdown image link to the branch’s resource:

![Topbar on mobile devices](topbar-closed.png)

The generated link is broken with Hugo 0.123 when baseURL is set with a subdirectory. E.g. for the themes documentation it’s baseURL = "". See live

I have a image render hook but it also happens with Hugo’s build in implementation.


<img src="../../basics/topbar/topbar-areas.png" alt="Topbar with default areas marked" class="figure-image bg-white border lightbox noshadow" style="height: auto; width: auto;" loading="lazy">


<img src="../../hugo-theme-relearn/basics/topbar/topbar-areas.png" alt="Topbar with default areas marked" class="figure-image bg-white border lightbox noshadow" style="height: auto; width: auto;" loading="lazy">

Interestingly the link render hook does not suffer from this.

Can you please look at this and tell me what’s different compared to your setup?

git clone --single-branch -b hugo-forum-topic-48441 hugo-forum-topic-48441
cd hugo-forum-topic-48441
hugo server

After adding this to hugo.toml, it is reproducible with your example

relativeURLs = true

	renderHooks.image.enableDefault = true

This just came up in my GitHub timeline: Multilingual, multihost site with relativeURLs enabled has broken links when viewing without a server · Issue #7805 · gohugoio/hugo · GitHub

Sounds familiar although in my case it is not multihost.


If it were up to me I would deprecate that option as well as canonifyURLs, and I probably wouldn’t be polite about it either.

It’s useful (and in my companies case mandatory) to use the documentation directly from the file system and a webserver. I know of no other way to achieve this besides running self-written post processing over the generated output.

1 Like

I’ll log an issue on this because the behavior changed, but I wouldn’t be surprised if it dies due to neglect.

The examples in this Tips & Tricks post use environments to control the behavior of sites that are built for online and offline viewing, enabling relativeURLs only when needed:

I also noticed that you are using canonifyURLs:

See It’s going to happen at some point; I’d plan for it now.

As the documented hugo.toml of the theme states, the canonifyURLs is only set to make the generation of sitemaps work in this environment.

This was tested a long time ago and Hugos behavior may have changed. I may get back to this, once the option isn’t available anymore. But as it does not affect the overall functionality of the page, I really don’t care much about this option.

I have a different view on relativeURLs. Our docs are rolled out into different environments. At the time we generate the docs, pretty much nothing is known about the target environment and due to limitiations we can’t just simply regenerate the docs in the target environment itself. Basically we are pretty much limited to simply copy over the resulting public folder.

All the same files are then accessed directly in the directory or by multiple webservers (running on arbitrary addresses - don’t ask…)

The relativeURLs options makes this kind of setup really easy for us.

Just to understand your view: What are your obligations regarding the releativeURLs option?

I assume you mean “objections”.

  • Both options are crude, like throwing a brick through a window instead of finding your keys then opening the door.
  • Both options are a form of post-processing, and can modify your content not just URLs.
  • Both options add too much complexity (multiply the number of related test cases by 4).
  • Link and image render hooks, along with relURL and friends, made canonifyURLs obsolete.
  • The relativeURLs option should only be used when building a serverless site, yet site and theme authors enable it globally, thinking it does something else without first reading the documentation. It’s a foot gun.

The canonifyURLs option will be removed at some point.

Even though serverless sites represent << 1% of the Hugo sites worldwide, I guess we need to keep the relativeURLs option. But I have no interest in supporting its global use; it should only be used when building a serverless site (i.e., enable it by environment with --environment CLI flag).

Do not enable this option unless you are creating a serverless site, navigable via the file system.

1 Like

Thanks for the insights.

At least it’s a regression from pre-0.123 versions. From your explaination and the links to the docs I understood that I am in undefined-behavior-land if baseURL != "/" and relativeURLs = true.

So filing an issue would be pure noise, I guess?

I’m not sure about that, but it’s definitely in joe-does-not-support-this-land.


I’ve opened a ticket.

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