Pictures not shown, because bundle folder has uppercase and Hugo creates lowercase folder

Hi there,

I’m not even sure whether this is an Hugo issue, or whether it should be mentioned with GitLabs CI-CD.


The TLDR is that hugo is creating a lowercase folder to shove the index.html into, while the image is in a folder with an uppercase in it (the original “” also has those uppercases). This causes the html to be unable to reach the image and it does not show up.


I have created a pipeline with multiple stages, to act as an internal “Hugo preview” for changes on content files. When merged to main the changes will be pushed to another repo that is public. On both I’m working with GitLab pages.

my stages

  • I pull hugo files from another repo, and filter out some pieces of content that are for internal documentation. I assign the hugo and content folder as artifacts.
  • If not main branch, I adjust the URL in the config.toml for the internal preview. I hand over both folders as artifacts again (afaik previous artifacts are available for all following jobs, but I only read up on that later)
  • Another stage where I filter out content files with specific frontmatter that says its internal. Handing over artifacts again (only main branch)
  • deploy stage: (except main) basically just hugo -D and handing over the artifact public to the pages deploy job
  • deployment for main is still wip

The quirk

Until deploy stage it all looks good. I checked the different artifacts and they were still fine. But then I noticed that on the last artifacts, the ones I download are different to what I see when I browse them in GitLab. There are two folders in GitLab (probably also linux systems, I did not test that).
The folder with uppercase contains the image, the lowercase one contains the .html file, so the html cannot find the picture with the relative path that is used.

Downloaded artifacts of the last 2 stages.
Browsed artifact of the pages deploy stage.

Question bug or behaviour?

So now the question is: is this a bug ?
(In my opinion Hugo should either create a folder that fits the filename exactly OR make sure that present folders are changed to all lowercase accordingly.)

If this is intended behaviour, do ppl have workarounds? I have thought about making all files and folders lowercase by default (with a CI-CD job) and also parsing all Markdown-files for filepaths and change them to lowercase, but I thought I’d ask first.

You can set:

disablePathToLower: true.

See Configure Hugo | Hugo

I should’ve known there was an option like this. Thanks a lot!

Nevertheless I believe that this behaviour is still incomplete, since it produces two folders with the same name but different spelling (upper-/lowercase).
I cannot think of any situation where this would be the expected or wanted behaviour.

I can’t confirm your find. Did you clean the destination directory, e.g. with flag --cleanDestinationDir.

Do lower/uppercase folders have the same content after build?

I did not clean the destination directory, but since it is a Gitlab Runner its usually creating a fresh (reseting git repo to head) environment (at the start of the job)

The contents of the folders are split - the uppercase contains the image, the lowercase contains the html - which is causing the issue of the broken images (I think). I failed to report that important detail.

I’ll try to provide/recreate a simple example repo that showcases the issue within the next few days.

1 Like

Hi @mahoromax ,
We are also facing the same issue but using different CI/CD. So looks like its the hugo behavior. Did you get any information about why its happening?
Thank you very much!

mahoromax / hugo-folder-case · GitLab
I tried to replicate it super easy.

The idea is that windows FS treat “folderXY” and “folderxy” the same, but linux ones don’t.

But then running this locally (windows) did not show the image in the mixed case folder (eehhh why?).

I tried building in a WSL Ubuntu (in the mounted windows folder)… but then I realised this would probably not reproduce, hugo 0.68 ran through though without issues.

Then I pulled the repo on a debian VM, and running it locally or building failed with missing templates. Since it only found hugo 0.55 I thought it was a version incompatibility. But then the same happened on an Ubuntu VM with the same hugo version as in my WSL distro.

So I have more questions than answers right now.

If @GhsvsDe or anyone wants to try to confirm my problem, this is the project it happened in originally:
TA_Alex / action-items · GitLab (
Rename the plotid to plotID (folder + .md), and before building reproduce the first step from the gitlab-ci.yml (move all files+folders from root except 00_, hugo, README … into the pages-content/action-items/ folder)

@rcpnair I did not find out anything new. Apparently hugo has a function to turn paths into lowercase, which includes build paths for html. So the html lands in a different folder to my picture and can’t be accessed.
For now I’ve manually changed my folders and filenames to use lowercase, and I’m planning to turn all .md and folders into lowercase with a bash script in the CI-CD, that way I won’t have to depend on people reading instructions, and also I won’t interfere with the functionality to turn stuff into lowercase (because this would most likely break another thing).
But keeping the option “disablePathToLower: true” in all configs should work fine as well…