GitHub Actions Deployment and BaseURL?

Hi everyone,

I am trying to sort out deploying my site using GitHub Actions, and running into some confusion? I am running into an issue with the BaseURL (I think?):

For GitHub Pages, it wants my the Base URL to be: < my-repo-name-here > /

that is, it is two levels deep and includes the repo-name.

I have tried just about everything to make it work, but the only way I can get my static content (images, css) to load properly is to add “my-repo-name” to every reference in all my HTML / partial / .md files?.

So as in: instead of doing something like:

<img src="/img/example.png" />

I seem to have to always write it as:

<img src="/my-repo-name/img/example.png" />

This doesn’t seem right, does it? Or is that the expected behavior for something like this? It feels very odd when writing the content, since that extra folder layer does not exist in my local folder hierarchy?

I should note that I also have to include the repo name again in the baseURL in my config.yaml for my site to serve properly when running locally? Is that normal to have that folder specified twice like that? This is noted in the docs, but seems weird that I have to do it here, and in all of my content?

For reference, I am using the default Hugo Action that can be loaded from the GitHub Pages site, with only small modifications to the paths.

Is there a good example of how to setup the config for a GitHub pages with a second layer like this?

thanks so much for any input or suggestions.

Yes, that is correct. URLs beginning with / are always relative to the root of the site (i.e., the protocol+host portion of the baseURL).

Please note that some themes fail when the site is served from a subdirectory—they were not designed to support this configuration.

For images referenced in markdown, consider page bundles.

├── post/
│   └── test/
│       ├── example.png
│       └──



You might also consider markdown render hooks for images and links.

Thank you @jmorring, that is very helpful to understand. I am glad that it doesn’t seem like I am doing anything too off-base here.

I think the distinction between the “baseURL” and the “Root” URL was what was confusing me here? So am I right to say that even when I specify the “baseURL” with multiple levels like:

all the links in the document (if preceded by a ‘/’) will still refer to the ‘Root’ URL (in this case: “https:://” ), not this ‘baseURL’ ?

Regardless: I will take a look at bundles and render-hooks as well.
Thank you!

Yes, that is correct.

URL resolution is not a Hugo thing. It’s a web thing.