Link to static HTML regardless of root address

I’m looking for a way to express links to statics file in my site, regardless of the actual root URL where my site is hosted.

The static files I want to link to are in <site root>/api_reference, so they’re at the same directory level as /content. I want to code a relative link to them, so that
<a href="<some_url>"><link_text></a> is converted to a valid link, regardless of the URL where the site is hosted.


  • <some_url> is /example_reference.html#tag/Create-Example
  • <link_text> is “Create an Example”


  • If I serve the site from my local Hugo instance (hugo server), then my root URL is localhost:1313, and I want the HTML tag to be
    <a href="localhost:1313/example_reference.html#tag/Create-Example">Create an Example</a>
  • If I serve the site from a preview server
    (, I want the HTML tag to be
    <a href="">Create an Example</a>
  • If I serve the site from my main server (, I want the HTML tag to be
    <a href="">Create an Example</a>

I don’t want to code the exact URL into the content; what I want is to use something that’s relative to the site root, and let Hugo do the rest. I tried this shortcode (html_ref.html)
<a href="{{- .Get 0 -}}">{{- .Inner -}}</a> and called it using

{{% html_ref "/example_reference.html#tag/Create-Example" %}}Example{{% /html_ref %}}

If I run this on my local Hugo server, the tag comes out as
<a href="http://localhost:1313/example_reference.html#tag/Create-Example">Example</a>
which is what I want.

If I run this on my main site, the tag comes out as
<a href="https"//">Example</a>
which is also good.

If I run this on my preview site, the tag comes out as
<a href="">Example</a>
which doesn’t work because the second part of the path is missing. It shoud start with
but it doesn’t.

How do I fix what I’m doing so it works in all three scenarios?

With your main site and preview site, do you set baseURL appropriately in your config file?

Have you tried using .Site.BaseURL?

Good questions. I currently have baseURL set to "".

I have tried using .Site.BaseURL, but it doesn’t help.

What seems to happen is that Hugo can figure out base URLs of the form


but can’t seem to work right on base URLs that have the form


without explicitly setting baseURL.

Yes. It seems that sites in subdirectories cause people some trouble. There’s quite a few threads on the forum about this. I think the reason is when baseURL isn’t defined, Hugo assumes baseURL = "/" (as in the root directory). Depending on how templates are built, this can sometimes break things if the site is in a subdirectory.

My baseURL is defined, but it’s empty. That might cause problems as well. I’m going to pursue the idea of setting the baseURL explicitly for each configuration I expect to use.

1 Like

An empty baseURL is invalid, a value must be entered for a Hugo project to function properly.

As per the description in the 1st post of this topic, why don’t you simply include the directory /api_reference under the staticDir and reference its children with relative links from whatever content file you need, (using a shortcode or not).

This approach should work for all 3 variations of the project.

? /api_reference is defined as a static directory in config.toml, using the following line:
staticDir = ["static", "api_reference"]

I’ll accept that you’re right about an empty baseURL value, although I can’t find anything in the documentation that says this.

Meanwhile, I’m going to test a hypothesis I have.

I am not a maintainer of the Hugo Documentation. I am a maintainer of the Hugo Themes Showcase.
One can maintain only this much on a voluntary basis and limited spare time.

Pull requests to the Hugo Docs are always welcome.

It doesn’t seem to apply here, but for googlers with a non-trivial baseURL.

For linking to images in static, I found it useful to include <base href="{{ .Site.BaseURL }}"> in the HTML header (source). Then, e.g. image::img/screenshot.png correctly resolves to file static/img/screenshot.png in the source repo.