Understanding .BaseURL and .RelPermalink


I had understood that .RelPermalink was a relative link to .Site.BaseURL and that .Permalink was equivalent to {{ .Site.BaseURL }}{{ .RelPermalink }}.

This works fine fine with simple cases, but if I use complex BaseURL, I’m getting a different behavior.

Here is the configuration I set in config.toml:

baseURL = "http://example.org/some/directory/"

With the following layout:

{{ printf "baseURL      : %s" .Site.BaseURL }}<br>
{{ printf "Permalink    : %s" .Permalink }}<br>
{{ printf "RelPermalink : %s" .RelPermalink }}<br>

I get:

baseURL      : http://example.org/some/directory/<br>
Permalink    : http://example.org/some/directory/films/o_brother/<br>
RelPermalink : /some/directory/films/o_brother/<br>

I was expecting to get:

RelPermalink : films/o_brother/<br>


RelPermalink : /films/o_brother/<br>

So I think I’m not supposed to use .Site.BaseURL and .RelPermalink together.
What is .RelPermalink relative to ?

1 Like

Alle local links don’t need the base URL. Using .RelPermalink generates smaller html pages. All browsers will generate complete URLs for requests.

I use .Permalink only in RSS feeds and in standalone files.

You can set the following in the head-section, if you need it.

<head><base href={{.Site.BaseURL }} /></head>


I’m using a theme which uses a lot of absolute references,
using href="{{ .Site.BaseURL }}{{ .RelPermalink }}" or href="{{ .Site.BaseURL }}{{ .URL }}".

These links get broken with complex BaseURL like in my example above :

{{ .Site.BaseURL }} = http://example.org/some/directory/
{{ .RelPermalink }} = /some/directory/films/o_brother/
--> href = http://example.org/some/directory//some/directory/films/o_brother/

It seems as you mention that href="{{ .RelPermalink }}" is enough, if I don’t define any base element in the head-section of the page.

This means that all links in the page, and thus in the content.md file, should be relative to the root of baseURL ( http://example.org/ ) and not relative to BaseURL itself, or to the root of the hugo directory.

If I want to define a link in a content.md file, I can use the relref shortcode to define a relative link to another .md file:

{{< relref “/series/Dr_House.md” >}}
–> /some/directory/series/dr_house/

But how should I define:

  • a link to a another part of the site where there is no .md file, like the tag page
    http://example.org/some/directory/tags/george_clooney/ ?

  • an image located in hugo’s static files directory (/static/img/image.jpg) ?
    I didn’t see how to define relative links with the figure shortcode.

I find out a way to get the path relative to baseURL, i.e. films/o_brother/ in your example:

strings.TrimPrefix (relURL "") .RelPermalink

I use this to make up the link to the archives of the current list page (section or term):

{{ printf "/%sarchives" (strings.TrimPrefix (relURL "") .RelPermalink) }}