Hugo: Handle absurl replacement in inline style elements

[onedrawingperday]

Not sure if this is a bug but I am opening due to this comment: https://github.com/gohugoio/hugoDocs/pull/676#issuecomment-443371219

This behavior is documented in the Themes repository's README:

Common Permalink Issues

The demo of your theme will be available in a sub-directory of the Hugo Themes website.

• You need to create absolute paths in the templates for the theme's assets, by using either the absURL function or .Permalink. Also make sure not to use a forward slash / in the beginning of a PATH, because Hugo will turn it into a relative URL and the absURL function will have no effect.

And yesterday I sent and merged a PR to amend the Hugo Docs that stated the opposite to the above.

Missing assets have been the most common issue that @digitalcraftsman and me encounter with theme submissions due to the use of .relURL or relative paths in theme templates.

If this could be somehow resolved so that both:

• .Permalink and .RelPermalink
• absURL and .relURL

output the correct URL for sites that are published in sub-directories (like the demos in Hugo Themes), it would be great.

[bep]

Do you have some concrete examples of "bad behaviour"? E.g. themes where this is/was an issue?

[onedrawingperday]

Here is an example from a theme that is still pending.

I had to send a (now merged) PR to that theme's repo because there were too many instances of relative URLs in the templates: https://github.com/2-REC/hugo-myportfolio-theme/pull/5

To test on your own with the Hugo Themes Build Script you would need to add that theme as a submodule and then from within its directory revert commit https://github.com/2-REC/hugo-myportfolio-theme/commit/1df8a11aad052a624100df3700a75c2c22ff1a3f

Also here is the diff of what got "fixed" with the above PR: https://github.com/2-REC/hugo-myportfolio-theme/pull/5/commits/9c290b5d33160a7e943b1433296724e52e839aac

---

Furthermore, please note that this behavior has been going on since way before I started reviewing themes in the Hugo Themes GitHub repository. The original guidance regarding the need to use absolute URLs for theme assets is by @digitalcraftsman

Also as stated in this issue's title this behavior is present not just in the demos on the Hugo Themes website but also it exists in all Hugo projects that are hosted in subdirectories.

There was also another submission the other day and the theme author had completely rewritten Hugo generated permalinks on his own "due to the limitation of Hugo not providing truly relative links". See the author's comment here: https://github.com/gohugoio/hugoThemes/issues/515#issuecomment-445571596

Kind of unrelated sidenote: the review of the Midnight theme submission was one of the hardest and more time consuming ones that I ever did due to all the permalink complexity.

[bep]

There are some weird constructs in the theme you sent as an example ({{ .Permalink | relURL }} etc. makes no sense to me).

Skimming that change set, I can say that there is one known issue/limitation:

 style="background-image: url('{{ (printf "images/%s" .) | relURL }}');"

The above does not (currently) work with the combination of sub-path in baseURL + canonifyURLs, reason being that we don't do "canonify URL replacements inside style tags".

[onedrawingperday]

There are some weird constructs in the theme you sent as an example ({{ .Permalink | relURL }} etc. makes no sense to me).

Yes I forgot about that weirdness. Ok.

Here is another example.

This is another PR that I sent to the Hugo Shopping Product Catalogue theme:

https://github.com/kishaningithub/hugo-shopping-product-catalogue-simple/commit/78c86425e0bfdb1fd0490b0434585390973b439b

Note how URLs that start with a forward slash generate links that are relative to the root of a project and therefore are incorrect when the project is published in a subdirectory.

[bep]

Note how URLs that start with a forward slash generate links that are relative to the root of a project and therefore are incorrect when the project is published in a subdirectory.

The last example is constructing URLs from site params.

<a href="/foo">FOO</a>

The above URL points to the host root; Hugo cannot guess that the above should point to ... something else.

[onedrawingperday]

And finally here is another example that illustrates the wrong URLs outputted by relURL

This is another PR that I had to send due to the complexity of that theme (I have highlighted the diff of layouts/partials/head-theme.html for you to look at:

https://github.com/cshoredaniel/hugo-oldnew-mashup/pull/1/commits/cf823982cd8667763d683f2680a10681f9260ba0#diff-7a090ed8a787a737a667e3b902fc6371L12

P.S. There are plenty of examples the ones that I posted above are the most recent theme submissions from the top of my head, if you need more let me know and I'll post more links. (Also note that each submitted Hugo Theme has varying degrees of complexity)

[bep]

Given your last example:

<link rel="stylesheet" href="{{ "/css/base.css" | relURL}}"/>

The above behaves fine in my tests.

{{ if $.Site.BaseURL }}<base href="{{ $.Site.BaseURL }}">{{ end }}

I suspect it is the above construct that messes with the URLs (in the browser that is) in the last example.

[onedrawingperday]

{{ if $.Site.BaseURL }}<base href="{{ $.Site.BaseURL }}">{{ end }}

Ah... I hadn't noticed the above. Ok, as I said each theme submission has varying degrees of complexity and I don't remember everything.

More examples about relURL here:
https://github.com/shaform/hugo-theme-den/commit/cf7b65e04482d16efb057d06e9daf25a4d41be25

https://github.com/Tazeg/hugo-blog-jeffprod/commit/4487419c0dff3b348abbcbd72a20494a4ab9627f
In the above commit please note the comment by @digitalcraftsman

https://github.com/sakibccr/pristine/commit/e3c21896c2cc6bdb7202646791a343e74862c167
This commit -I think- that it best illustrates the problem.

Hope these examples are better.

[bep]

<script src={{ "/js/main.js" | relURL }}></script>

See https://github.com/gohugoio/hugo/issues/5529

Note that the above could be written as:

<script src="{{ "/js/main.js" | relURL }}"></script>

And it would work fine. I had to look in the HTML 5 spec to confirm that unqouted attributes are allowed (they are), but I'm so used to putting quotes around them that I never thought about it.

Also note that the reason why we do these replacements is because of the canonifyURLs=true.

[bep]

I have looked at the examples, and so far I see 2 cases where Hugo could improve with the combo of canonifyURLs=true and sub-path in baseURL:

1. "style="background-image: url('{{ (printf "images/%s" .) | relURL }}');" (i.e. URLs inside style tags; this is a known issue)
2. #5529

Is that a correct summary? @onedrawingperday @digitalcraftsman

[onedrawingperday]

As far as I can tell your summary seems fine. Unless of course @digitalcraftsman has more examples.

Thanks for looking into this @bep

[digitalcraftsman]

Is that a correct summary? @onedrawingperday @digitalcraftsman

This should cover all situations that occur to me spontaneously or have already been mentioned

[bep]

OK, but quote your relative URLs and use absolute URLs in style tags doesn't sound like a too hard rule to follow for me. I will see if I find time to fix these.

[onedrawingperday]

OK, but quote your relative URLs and use absolute URLs in style tags doesn't sound like a too hard rule to follow for me. I will see if I find time to fix these.

No it isn't.

I will send a PR to amend the README for the themes repo and another one for the Docs.

P.S. I removed myself from the Hugo Web team sometime ago. I'm still part of the organization but I don't belong in any team, so I no longer have merging rights in the Docs.

@bep I will tag you once I send the Docs PR so that you can review it and merge it.

[onedrawingperday]

Right.

So since #5529 (transform/urlreplacers: Support unquoted URLs in canonifyURLs replacer) was resolved with commit https://github.com/gohugoio/hugo/commit/f7691fe9652aa12b6c582dea0ae2555e772d1a5f

And

This very issue has been renamed to: Handle absurl replacement in inline style elements

The guidance at: https://github.com/gohugoio/hugoThemes#common-permalink-issues needs to reflect the above. (PR coming soon).

[bep]

@onedrawingperday correct. I may revisit the "inline style" problem later -- but that is a harder nut to crack.

[jvgelder]

Would this happen to be related to #5920
I cannot judge what the impact of that change would be but it works for me.