Best practices for moving root to subdirectory

Hi, I am new to hugo so forgive me if this turns out to be trivial, but I cannot find any satisfactory answers. Below you will find a link to a completely stripped down hugo file structure to explicitly demonstrate the problem I am happening. Actually, the readme file I have included probably explains the problem more clearly.

To summarise, I have a hugo site which runs perfectly when the baseurl is

However, I would like to deploy it in a subdirectory, say

What is the current best practice for doing this?

I have tried setting the baseurl to be and played around wiith setting relativeURLs and canonifyURLs to true, but this doesn’t help. Some of the links then work, but others do not. But the problem is that some hyperlinks in the html and css start with a slash: /images/… (either accessing the assets or static folder). And hugo does not seem to know that I want these to refer to as a base.

Here is an explicit example: ExampleHomeSubdirectory.

In this explicit example, I have an assets folder with assets/images/TestImage.jpg. I then have a shortcode to do some thumbnail. If I write

{{ $image := resources.Get (print “images/” .filename) }}
{{ $imageThumb := $image.Resize “200x” }}
<a href= {{ $image.RelPermalink }} class=“class”>

then the thumbnail appears with the correct image (located at, but its hyperlink refers to (which does not exist) rather than (which does).

Note that the hyperlink to “page 2” does work. On the other hand, if I do things like including relativeURL and canonifyURL to true, then the image links work perfectly, but the hyperlink to page 2 does not work anymore.

How should I proceed?

Many thanks.

The baseURL should end with a slash like this:

baseURL: ""

Then it should just work. If it does not then your theme is to blame.

Well yes I tried putting a slash at the end, with no improvement. Saying “your theme is to blame” is precisely the question in some sense. I have made my own very basic theme following standard practices.

Post a link to your repo and then we can help with that.

Hi - I have made a completely stripped down project structure (without any themes) to demonstrate the issue I am having. Please see the edited question.

This is what I get when I build that repo:

<a href= /subdir/images/TestImage.jpg >
    <img src="/subdir/images/TestImage_hu045ded699f2451b6adc01a1b8ba277b6_57659_400x0_resize_q75_box.jpg" class="Image-In-Blog">

So the image part works just as it should thanks to the use of the Hugo function “RelPermalink”.

The link to another page looks like this:

<p><a href="/new_page/">New page</a></p>

This link is hardcoded in the content file so Hugo just displays it as is.

If you want Hugo to rewrite this link based on baseURL you need to run it through a Hugo function that handle this.

One way would be to use the “relref” built in shortcode.

[New page]({{< relref "" >}})

This generates:

<p><a href="/subdir/new_page/">New page</a></p>

Hi that’s very good. There are two follow ups however (but this should finalise it):

  • One of my links in a markdown file is to a pdf in a folder in static. I can’t seem to make the relref work here.
  • There is one other place where they occur - I have an element in the css file with background-image: url(“/image1.jpg”). Again, I don’t think hugo allows a shortcode in these files, does it?

Perhaps you suggest just hard coding it in? But the problem is that I haven’t finalised the name of the subdir folder! So it is possible it may change! So it would be useful for hugo to know about this somehow.

[Edit: perhaps useful for other newcomers : in reality, my<a href=...>s occur in a layout (html) file (specifically in a nav partial in my theme). The baseurl can be fixed by writing eg <a href="{{.Site.BaseURL}}about">about</a> to link to the subdir/about page.]