Is there any 'baseURL' usage convention for themes?

support
1

With the couple of themes I had used before, most of the static content such as css, js and images, was referenced relative to baseURL. This allows to set a baseURL which is not the root of a domain, but a subdir, for example: mydomain.com/asite.

When I tried a different one, I realized that images where read relative to the root, i.e. the domain, no matter if a subdir was specified in baseURL. I asked the maintainer to change it, but when discussing about it we realized that there seems to be no convention:

  • Some take everything relative to the domain.
  • Some take everything relative to baseURL.
  • Some take everything relative to baseURL, except favicon and, maybe, images.

You can see the details here: https://github.com/halogenica/beautifulhugo/issues/26#issuecomment-285852628

Therefore Iā€™d like to ask whether there is any convention on this topic, which might be not easy enough to find. Or if itā€™s something you just havenā€™t considered it before.

2

Between this post and the issue thread, Iā€™m a little confused. I think most, if not all of your questions are answered in the docs, but they can be a little confusing ā€“ and there is a project to overhaul them which you might find more helpful.

If you want a site structure like:

1138-github.io/myrepo/
1138-github.io/docs/
1138-github.io/blog/

Is this not accomplished by using sections? And if you want:

  • root
    • /images
      • s1image.png
    • /site2
      • /images
        • s2image.png
    • /site3
      • /images
        • s3image.png

The docs say: ā€œEverything in the static directory will be copied directly into the final site when rendered. No structure is provided here to enable complete freedomā€¦The actual structure is entirely up to you, the theme creator, on how you would like to organize your files.ā€

Even though /myrepo, /docs, and /blog have different themes, it seems like combining it all into one Hugo site would be easiest and closest to any convention Iā€™m aware of. This explanation on section templates might be helpful. Youā€™d have to spend some time setting it up, but itā€™d probably be a lot easier to manage.

Regarding relative urls, itā€™s my understanding that we are supposed to use relURL for relative urls, but not everyone adheres to this. The docs explicitly say: ā€œBoth absURL and relURL considers the configured value of baseURLā€. I took a quick look at his repo and I donā€™t think I saw relURL. Maybe give that a shot?

Itā€™s late and Iā€™m tired, so I might have completely misunderstood youā€¦so donā€™t hate me if Iā€™m wildly off the mark :sweat_smile: :sleepy:

3

My recommendation is to always use the template funcs relURL and friends.

1 Like
4

@sethm, thank you for your interest, even at late night ;). Indeed, each of the sites already includes sections, and even subsections (using categories). Furthermore, the point is that not the three sites need to be built with Hugo. One of them might be a webapp, another one the documentation built with Hugo, the third one a wikiā€¦ For example, say there are ten students and there is a subdir for each of them to design their own page. They are all developed separately, but then put in the same server.

What I expected from any Hugo template is that, no matter if I use mydomain.io, mydomain.io/subdir or mydomain.io/very/long/sub/dir as the baseURL, that will be the root, and every content will be placed below in the hierarchy, not above.

Regarding relative urls, itā€™s my understanding that we are supposed to use relURL for relative urls, but not everyone adheres to this. The docs explicitly say: ā€œBoth absURL and relURL considers the configured value of baseURLā€. I took a quick look at his repo and I donā€™t think I saw relURL. Maybe give that a shot?

He told me that he will do it, with relURL or adding Site.Params.baseURL, but he wants to be sure about what the convention is before doing so. At now, this is what we are considering ā€˜the conventionā€™:

And in the hugo base theme, the themeā€™s CSS was changed to be relevant to the BaseURL (which I think is a good change) but favicon and apple-touch-icon.png are still relative to the domain (not sure if thatā€™s good or bad). I just checked a couple more themes and this seems to be standard for those themes as well.

But I personally think that it is not coherent to have everything relative to baseURL, except favicons.

@bep, does that recommendation apply to all the content, including favicons? If so, is there any drawback in asking it to be added to the documentation?