Understanding BaseURL and links

Short version (which is still long winded):
How come if I do:

baseURL = “https://pages.cs.wisc.edu/~gleicher/

things like (in a template)

< script async defer src="{{ “/js/menu.js” | relURL }}">

generate URLS where ~gleicher is duplicated. In general, most things that generate URLs (list templates, menus) generate URLS of the form “…/~gleicher/pages/bio/”, where “…/pages/bio” would have been correct.

{{< relref “/” “json” >}}

(in a content html file) does the right thing.

(or conversely, why does baseurl being “https://pages.cs.wisc.edu/” work most of the time, but not for the relref to json above)

Based on: CanonifyURLs & RelativeURLs interaction, more things seem to work if I set “canonifyURLs = true” (but not necessarily everything)

Longer version:

I had a very specific problem: I am trying to refer to index.json from a non-template (a regular content file), and it fails - but only when I run my website on my production server.

But, I realized that my problem is deeper: I simply don’t understand how to use URLs and references, and what baseURL does. So my sites (there are many of them) use a random assortment of tricks (usually relative URLs) rather than a consistent reference scheme based on me actually understanding how things work.

Background: my site (https://pages.cs.wisc.edu/~gleicher/, if you’re curious) is served from a directory on our file server. I use hugo to build things into that directory.

I set that url “https://pages.cs.wisc.edu/~gleicher/” as my baseURL - since I want everything to be relevant to that. But this breaks most things. In particular, URLs that get built by my templates mysteriously get an extra “~gleicher” in them. I assume this is because I build URLs incorrectly in a template.

I generally use “{{ file | relURL }}” but that leads to the doubling. Same problem if I do “.RelPermalink” on a resource (for example, for the favicon and css files).

So, instead I switch the baseURL to "“https://pages.cs.wisc.edu/” - and the relURLs miraculously work!

I’ve been happy for 6 months with this - but now I realize, that this is mysterious. My understanding of how things work doesn’t match reality - which means what I am making is brittle.

How should I understand baseURL?
Why does the doubling of ~gleicher happen?
Why doesn’t ~gleicher get doubled if I do “{{< relref …” in a content file?

If I switch to absolute URLs, I get differently broken behavior…
It seems like ~gleicher gets chopped off! (“foo.js | absUrl” gives me a link to https://pages.cs.wisc.edu/foo.js" - even though baseURL (the only place the url exists) has the ~gleicher in it.

Why does absURL chop the ~gleicher off?

I really appreciate an explanation. I have been able to make stuff work, but it will be much better for me in the long run if I actually understand why things work the way they do.

Thank you!


(And, as an aside… I really appreciate the responsiveness of the community to questions. It has made the multi-month saga of me using Hugo much more pleasant. I promise to be better about “giving back” in the future.)

Hi Mike,

This would be a lot easier to assess if you were to share a public repository for one of the problematic sites. There are a lot of moving parts (config, layouts, theme), and without code it’s just a guessing game – a game I’m not terribly good at.


Thank you.

I should create a new “test site” that is as small as possible, yet shows the problem.

I think this is my problem:

But, it doesn’t help me understand how things work.

My problem isn’t making things work - its understanding all the machinery so I can use it correctly.

Knowing how to avoid having baseURL chopped (sometimes) doesn’t help me why it was happening in the first place.

Thank you,


So, will you post a minimal test site for us to look at?