Document absURL and relURL’s behaviours with leading / slash

[anthonyfok]

absURL and relURL seems to ignore the sub-folder of the baseURL when it is given a path with a leading / slash, but that behaviour isn't documented in https://gohugo.io/functions/absurl https://gohugo.io/functions/relurl.

See theNewDynamic/gohugo-theme-ananke#103 for example.

TODO: Study AbsURL() and RelURL() in helpers/url.go (and maybe fix the comments there too) before touching hugoDocs

[kaushalmodi]

This has come up many times before.. I believe it's a bug.. but we need to document whatever the current behavior is.

Here's a recent thread with lots of detailed discussion.

[anthonyfok]

Okay, here is a historical account of what led to today's absURL behaviour:

1. Hugo 0.14: absURL and relURL were born:

   • In May 2015, @bep added absURL (Create absurl template func hugo#1106) and relURL (Add relURL template func hugo#1126) and documented them. At the time, both template functions had consistent behaviours, and gave identical output whether a leading / slash is present or absent.

2. Hugo 0.15: Same behaviour as in Hugo 0.14.

3. Hugo 0.16: absURL's behaviour changed, and remained the same to this day:

   • In Nov 2015, @mjanda filed Make absURL properly handle baseURL with path component hugo#1540 (Make absURL properly handle baseURL with path component) and Apply absURL on social tag urls hugo#1542 (Apply absURL on social tag urls). The latter was merged first and entered Hugo 0.15, while the former was merged as gohugoio/hugo@0962470 a several months later and landed in Hugo 0.16.

   • @mjanda gave the reason for changing absURL not in PR#1540 but in PR#1542:

     I use baseURL with path component (http://example.com/blog/) and reference my images like /blog/xxx/xxx.png etc.

     This PR together with Delete the news page "HTTP/2 Server Push in Hugo" #1540 will allow me to use those relative paths in images frontmatter array.

   • From the test cases that @mjanda wrote in gohugoio/hugo@0962470, it can be seen that:

     • Given baseURL = "http://base/path":
       • {{ absURL "test/2/foo/" }} gives http://base/path/test/2/foo/
       • {{ absURL "/test/2/foo/" }} gives http://base/test/2/foo/

   • The documentation was not updated to reflect this change, and Make absURL properly handle baseURL with path component hugo#1540 didn't make it to the Hugo 0.16 release notes either.

   • No corresponding change was made to relURL, hence {{ absURL "/test/2/foo" }} and {{ relURL "/test/2/foo" }} produce different results, for better or for worse.

[anthonyfok]

See also https://discourse.gohugo.io/t/problem-with-relurl-on-hugo-themes-demo-sites/11850 (Problem with relURL on Hugo Themes demo sites)

And MunifTanjim/minimo#121. Is it really a Hugo bug as @MunifTanjim suggested? Or is it something else? Oh! Indeed! Running hugo with the environment variable HUGO_CANONIFYURLS=true changes relURL's output! Hmm....

[anthonyfok]

Extensive discussion HUGO_CANONIFYURLS=true here: https://discourse.gohugo.io/t/baseurl-path-subdir-sometimes-ignored-by-relurl-absurl/11512 (Thank you @kaushalmodi for providing that link!)

[kaushalmodi]

@anthonyfok You're welcome. Here's a test page (that I also link in the discourse thread you linked), that summarizes the absURL vs relURL vs canonifyURLs: https://hugo-sandbox.netlify.com/subdir-canonify-true/.

This inconsistency definitely looks like a bug to me. I hope it gets fixed.

[bep]

Not sure what the issue is, but I just wanted to point out that:

• When canonifyURLs = true, we make absolute URLs out of relative ones from the rendered HTML output
• Since the above is a stupid search and replace that prepends the baseURL, the output from relURL cannot have any sub-paths in it if this is going to work.

So, whatver you do to verify "correctness", if will have to be the rendered output (and not some debug output of relURL.

Hope that helps.

[anthonyfok]

Thank you for the clarification, @ bep!

Not sure what the issue is...

There are actually a few separate issues that got kind of mixed into one single GitHub issue about clarifying absURL/relURL documentation:

1. @mjanda's change to absURL (leading / slash) in Hugo 0.16 needs to be documented.

2. (canonifyURLs = false) relURL did not get the same change about leading / slash (which I just realized today), and we should probably discuss in a new issue over at gohugoio/hugo whether relURL should also drop the baseURL sub-path component like absURL does when given a leading / slash.

3. relURL's behaviour when canonifyURLs = true, which @kaushalmodi and you clarified. It is again an entirely different issue, which I just realized about an hour ago.

So, yes, it suddenly became a lot more complicated than I thought. (I went dumbfounded... my head sort of exploded.) But your clairification did ease my fear a lot. :-)

Moving forward:

• We should document the current absURL and relURL behaviours, especially those which catches users by surprise.
• In the more distant future, should we consider changing relURL's behaviours (regarding points 2 and 3)? [To be discussed]

[bep]

Also see gohugoio/hugo#4733

[stale]

This issue has been automatically marked as stale because it has not had recent activity. The resources of the Hugo team are limited, and so we are asking for your help.
If you still think this is important, please tell us why.
This issue will automatically be closed in the near future if no further activity occurs. Thank you for all your contributions.