Hello
I plan to use hugo for my software documentation and its website. The purpose of the documentation is to be read locally on the filesystem too, so no domain should be used in the urls.
I’ve tried to enable relativeURLs = true in my configuration but any attempt to use {{ .Site.BaseURL }} still replace the urls with the full domain.
Unfortunately lots of theme use .Site.BaseURL so changing it would be difficult and hard to update.
Do I miss something in my configuration? What should I do if I create my own theme?
For example, I would like this: <link type="text/css" rel="stylesheet" href="{{ .Site.BaseURL }}css/materialize.min.css" media="screen,projection"/>
To be replaced by something like: <link type="text/css" rel="stylesheet" href="../../../css/materialize.min.css" media="screen,projection"/>
If the page rendered is 3 directories below the root context.
Thanks, that’s a bit better. However it does not work if you have a baseurl set to http://foo/apath because the relURL function will convert as …/…/apath/blabla.css.
But I can deal with that by changing the baseurl before generating.
You are probably right in the big picture of it, but the relURL func does not create URLs that look like that – but will create URLs relative to the host/server root, i.e. “/apath/blabla.css” – I thought the relativeURLs feature handled that baseURL sub path, but I may be wrong.
I was about to post a question with a similar set of issues with relativeURLs. I think what he meant was that relURL will do as it is supposed to and give you an URL with the context root, which then will be handled by relativeURLs adding the …/…/etc as it thinks is needed so the link you see ends up in effect have the context root part doubled when you look at the link the browser shows.
I basically just don’t see how one would use relativeURLs with a baseURL set to anything other than a root based URL with no subdir. Otherwise you get issues with the doubling for the menu items thanks to Hugo automatically adding context root to the user supplied menu item’s .url setting, and the same type of issues with relURL relLangURL, .RelPermaLink and even .URL (since unless a url is provided in the content’s front matter, it just uses .RelPermaLink itself).
I kind of wonder if the answer is the belatedly obvious one of just always using baseurl="/" but then that would mess up any actual .PermaLink uses, absURL, etc., right? So maybe relativeURLs=true just needs to be context root aware in it’s processing of urls.
I would really love someone experienced to write a best practices guide to making truly relative relocatable sites and themes that don’t rely on how they happen to be deployed. I don’t think it’s possible to actually, really do cleanly as of now, and if true, then that’s a shame. I hope it’s just lack of experience that can be corrected, then documented so others can learn it more quickly.
Quick example:
Given config.toml settings: relativeURLS=true baseurl=http://host.com/examplesite
Let’s say you use .RelPermalink as the docs suggest in making read more links, etc. in your theme with a line such as this: <li><a href='{{ .RelPermalink }}' class="button small"><nobr>"{{.URL}}" Read more →</nobr></a></li>
(the {{.URL}} is in there just to demonstrate that in non-front matter specified cases It is the same as .RelPermalink)
The rendered html will look like: <li><a href='./examplesite/post/image-relpath-test/' class="button small"><nobr>"/examplesite/post/image-relpath-test/" Read more →</nobr></a></li>
and when the browser (any modern one) gets that, if you hover over it, it’ll show that as a link to: http://host.com/examplesite/examplesite/post/samplepostname/
with the (depending on browser) path portion being a lighter grey than the host portion, indicating that’s the computed form of the relative path.
Same thing will happen with menu entries, with relURL() and, I presume, relLangURL().
Certainly there’s discipline required, but would it be reasonable for the relativeURLs=true code to check for context root before writing the relative urls out? I suppose whatever the context root dir is, it could theoretically be also a valid subdir (someone names their blog “images” ?) but that seems unlikely?
Otherwise unless I’m missing something it pretty much forces a no subdir type baseurl, or forces themes to be very aware if the user is using the setting (yet there doesn’t seem to be a way to check if the setting is on or not from the site variables available in templates) and forces absolute urls in the config file for menu entries.
I was fiddling around with this the last few days and since half an hour I have a complete site (blog section and traditional home page all-in-one) working without any issues on my local file system (without using hugo server).
I use .RelPermalinks, relURL and set uglyURLs = true, relativeURLs = true, canonifyURLs = false and in fact it is essential NOT to set baseURL to anything other than http://www.domain.tld - NO additional folders are allowed here.
But as the site is truely portable you may install it anywhere on the server I think. Will test this tomorrow.
Yeah, the no additional folders is key, but then you can’t use any absURL, .Permalink, etc., anywhere else in the site. That worked fine for me creating my own site and theme, but many of the examples from the documentation and most of the themes I’ve seen do use them in some areas, and .RelPermaLink, etc. in others.
With it set to “/” I could use .RelPermaLink still. For some reason (I forget now) I still ended up needing to remove my RelURL calls.
I didn’t use uglyURLs=true, so when I look at the site as a file, the browser wants to open the linked directories, but at least it now works both locally under Hugo server and as a project site under gitlab, and should work under a host only site. In my case it wouldn’t work as a file based setup anyway unless I also changed from using the built in youtube shortcode which now uses “//youtube.com” instead of specifying the schema.
I think the requirement to have baseurl set to host only or just plain “/” would go away and allow AbsURL, .Permalink, etc. to be used if the relativeURLs code took context root into account and either just left those urls alone (though that’d break filesystem viewing which may be a main requirement of that feature), or just remove the context root portion before doing the current rewriting as fully relative.
I see it that way: as long as the rendered public folder is just working on any filesystem - it will work on any webserver at any location, beeing it root or any subfolder.
One additional issue I found with trying to use relativeURLs=true and a baseurl of “/” (which you have to do or you can’t use .RelPermaLink, etc., as explained above)…
404 pages are fairly unworkable, at least for gitlab pages. You would want to use a correct baseurl setting for them, since you can’t know what the path will be that they’ll be served from, then use absURL or relURL, .RelPermaLink, .PermaLink, etc. for the links inside. As is, I can’t see a reliable way to even provide a link back to the home page.