Link to static HTML regardless of root address

support
1

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.

Suppose:

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

then:

  • 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
    (http://preview.example.com/api-docs/this_preview/), I want the HTML tag to be
    <a href="http://preview.example.com/api-docs/this_preview/example_reference.html#tag/Create-Example">Create an Example</a>
  • If I serve the site from my main server (https://main.example.com/), I want the HTML tag to be
    <a href="https://main.example.com/example_reference.html#tag/Create-Example">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"//main.example.com/example_reference.html#tag/Create-Example">Example</a>
which is also good.

If I run this on my preview site, the tag comes out as
<a href="http://preview.example.com/example_reference.html#tag/Create-Example">Example</a>
which doesn’t work because the second part of the path is missing. It shoud start with
href="http://preview.example.com/api-docs/
but it doesn’t.

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

2

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

Have you tried using .Site.BaseURL? https://gohugo.io/variables/site/#site-variables-list

3

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

https://www.<domain_qualifiers>.<domain>

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

https://www.<domain_qualifiers>.<domain>/<path>/

without explicitly setting baseURL.

4

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.

5

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
6

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.

7

? /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.

8

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.

9

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.