I cannot get my Hugo site working

support
1

This will probably sound like hyperbole, but Hugo, at least for me, on my mac, seems completely busted, in many many ways. I realise a minimal reproducible test case would be most helpful, but the issue I’m having is that everything about hugo seems completely jank. You can not all be using a piece of software this bad, so I assume the problem is me, but I’ve no idea how to even start debugging.

It’s proving impossible to learn the framework, because nothing works reliably or reproducibly, and I can’t tell if things are not working because I’ve done the wrong thing as a beginner, or my hugo is just busted once again.

My setup:

M1 Pro Macbook, OS X 14.1.
hugo v0.131.0+extended darwin/arm64 BuildDate=2024-08-02T09:03:48Z VendorInfo=brew

Running server with --disableFastRender --disableLiveReload, but I’m also seeing similar issues if I rm -rf public && hugo

Some of the symptoms:

  • only a handful of items in a large collection appearing in lists
  • changes to content items only being reflected on adding/editing/sometimes deleting an _index.md
  • changes to baseof.html being completely ignored on some pages
  • Live reload not working correctly - complaining about syntax errors have been corrected (in a one line file), even when I force-refresh the page
  • Most recently, I added a bunch of assets to static, and now nothing from content is being processed to public at all. I’ve since emptied static, rm -rf public, but still barely anything apart from my stylesheets and /index.html are being processed. I know hugo is seeing the content in content, because I can see some debug logs referring to files in there, but it’s not outputting anything.

In short, everything is broken, there are no helpful errors. Sometimes restarting hugo server fixes the issues. Sometimes it doesn’t.

I have been a professional software developer for 25 years, and I have built sites in both nanoc and jekyll, so I have some experience of how things ‘should’ work in a project like this, even if some of the details are new to me.

Assuming you’re not all using a tool which flat-out does not work, can anyone give me some support to begin getting to the bottom of this? I’d genuinely like to use hugo, but right now I’m having no luck.

2

Yeah, that one.

You are more likely to receive a prompt and accurate response if you post a link to your project’s Git repository.

See Requesting Help.

Let us see your code

Include a link to the source code repository of your project, because we really need the context of seeing your templates and partials to be able to help you. It is trivial to do a quick git clone on your repo, then run hugo server in your project, to help you out. On the other hand, recreating your code from screenshots, or sort of guessing at it, is not.

If you can’t share your repository for whatever reason, consider creating a dummy repo that you can share, which reproduces the problem you’re experiencing.

1 Like
4

I can assure you that the tool itself is not mishaving. This is a “you” problem.

We’re happy to help, but we need to see your repository.

There are thousands of live Hugo sites, some simple, some very complex.

image
image2176×1258 721 KB

6

The repository that you share should be a minimal reproducible example that demonstrates the problem you are having.

If you are having trouble creating a basic functional site, you can follow the quick start guide:
https://gohugo.io/getting-started/quick-start/

I’m out for the rest of the day, so perhaps someone else can pick up this thread as needed.

7

Cool.

I do realise I’m asking a lot, but if anyone has time to read what I’ve actually written, and suggest some pragmatic troubleshooting steps, I would be grateful.

I understand people are just volunteering their time here, so certainly no expectations, just gratitude if anyone does have any pointers to help me understand the avenues I have to debug this and become a successful, happy, hugo user.

If it helps, I am aware the hugo documentation exists, having spent much of the past two days reading it.

8

It doesn’t help – you describe perceived problems, but how can anybody know what their source is? And your description is so general as to be, apologies, useless.

Then you know that the first step to solving a problem it to describe it so that others are able to help. And so that they can reproduce the problem.

9

It doesn’t help – you describe perceived problems

I’m not sure what you mean by ‘perceived’. If you mean in the sense that I ‘perceive’ these problems, i.e. I have experienced them, that’s correct. If you mean in the looser sense that these problems are only ‘in my imagination’, that’s not quite accurate. These are a concrete list of problems I have experienced, repeatably, over the past two days, in some cases which were only fixed by quitting and restarting hugo.

how can anybody know what their source is

I was hoping that people having more experience than me with the tools in question, and some empathy would have experienced similar problems in the past. It may be that this is completely isolated to me and my computer, but the chances are that another human being has experienced similar at some point, and can infer where I should start looking to fix this.

your description is so general as to be, apologies, useless […] the first step to solving a problem it to describe it so that others are able to help

If any of the specific issues I’ve listed are still too vague, I can provide more detail, I’m strongly-incentivised to get this working.

10

You could share a link to you repository or provide a minimalist test case that exhibits the perceived problems (English is not my first language).

I, for one, don’t experience nor perceive any of the issues you mentioned. So, I can’t tell you anything from this experience.

11

English is not my first language

No worries, I appreciate you trying!

So, I can’t tell you anything from this experience

Hoping somebody can!

12

OK,

Here’s something close to a minimal test-case:

As I’ve tried to explain, these issues are fairly nondeterministic. I’ve committed my local filesystem, including the public directory in exactly this state because it illustrates what I’m experiencing quite well. This is immediately after a rm -rf public && hugo server:

  1. see how in public/case-studies, only two case studies have been output. This was previously zero, no matter how many times I quit/restarted hugo, but I triggered ’something’ by moving all the files out of the directory and back into it. However, as you can see, it only built the first two and then gave up.
  2. Notice that guides is not output at all. They were previously outputting fine, but I tinkered around in my CSS for a while, trying to reduce what was there for a minimal test, and eventually, guides stopped being output.

(Also in the course of prepping this, I had the ‘changes to baseof.html don’t trigger changes in files that depend on it’ issue: two browser tabs side by side, one displaying the updated template, one refusing to change. Should have possibly taken a screen capture to illustrate).

If I have done something massively and obviously wrong here, then I’ll happily eat humble pie if someone can point it out… All I really want to do is get this fixed and crack on with my site rebuild.

If, however, people pull this and it works fine for them, I will be eternally grateful to anyone who’s able to suggest any avenues I can explore to work out why hugo is acting so strangely on my computer

FYI here’s the console output immediately prior to the filesystem being in this state:

You’ll see the first block of ‘source changed’ when I remove all the files from the directory, and a second when I replace them. Hugo is obviously aware of the files in content, but for some reason only two folders are output into public/case-studies. A few minutes earlier, all were output.

Source changed /case-studies/chartboost.md
Source changed /case-studies/covea.md
Source changed /case-studies/deathwishcoffee.md
Source changed /case-studies/gbg.md
Source changed /case-studies/how-marmalade-insurance-improve-customer-experience-case-study.md
Source changed /case-studies/how-polypipe-learnt-to-benefit-from-customer-feedback.md
Source changed /case-studies/how-the-digital-marketing-institute-improves-net-promoter-score.md
Source changed /case-studies/kk-wind.md
Source changed /case-studies/optimus.md
Source changed /case-studies/philips.md
Source changed /case-studies/spark.md
Source changed /case-studies/swiftpage.md
Source changed /case-studies/tastecard.md
Source changed /case-studies/ubt.md
Web Server is available at http://localhost:1313/ (bind address 127.0.0.1)
Total in 17 ms

Change detected, rebuilding site (#2).
2024-08-09 17:52:10.815 +0100
Source changed /case-studies/chartboost.md
Source changed /case-studies/covea.md
Source changed /case-studies/deathwishcoffee.md
Source changed /case-studies/gbg.md
Source changed /case-studies/how-marmalade-insurance-improve-customer-experience-case-study.md
Source changed /case-studies/how-polypipe-learnt-to-benefit-from-customer-feedback.md
Source changed /case-studies/how-the-digital-marketing-institute-improves-net-promoter-score.md
Source changed /case-studies/kk-wind.md
Source changed /case-studies/optimus.md
Source changed /case-studies/philips.md
Source changed /case-studies/spark.md
Source changed /case-studies/swiftpage.md
Source changed /case-studies/tastecard.md
Source changed /case-studies/ubt.md
Web Server is available at http://localhost:1313/ (bind address 127.0.0.1)```
13

FYI see also the case-studies-are-back branch, showing the effects of two subsequent rm -rf public && hugo server runs in 2 back-to-back commits. I dropped my full console output into the second commit.

14

The first thing that comes to mind is that your case-studies is a leaf bundle, since it contains an _index.md. From the documentation:

A branch bundle is a directory that contains an _index.md file and zero or more resources. Analogous to a physical branch, a branch bundle may have descendants including leaf bundles and other branch bundles. Top level directories with or without _index.md files are also branch bundles. This includes the home page.

But you put all your case-study source files into this branch bundle. If instead you create a structure like

case-studies
├── _index.md
├── barchester
│   └── index.md
├── chartboost
│   └── index.md
├── covea
│   └── index.md
├── deathwishcoffee
│   └── index.md
├── gbg
│   └── index.md
├── how-marmalade-insurance-improve-customer-experience-case-study
│   └── index.md
├── how-polypipe-learnt-to-benefit-from-customer-feedback
│   └── index.md
├── how-the-digital-marketing-institute-improves-net-promoter-score
│   └── index.md
├── kk-wind
│   └── index.md
...

all your case-studies get created in public.

So, this is actually not a Hugo problem. Never was. Perhaps reading the documentation carefully (and following its guidance) as well as posts in the forum (the topic of leaf vs. branch bundles has been discussed here ad nauseam) could have de-frustrated you earlier.

Please fix your guides section in the same way.

Aside: It might be easier to get on a learning curve with Hugo if you use a simpler setup. Why do you have a myriad of SCSS files that result in more than 500 CSS rules? Why do you assign a layout to your case-studies _index.md that you then cascade, instead of putting single.html and list.html templates in your layouts/case-studies? And what are these &desc and *desc things doing in your description front-matter?

And please set your baseURL to the base URL of your site. Do it now. It doesn’t do any harm with hugo server, but you’ll be very sorry if you run hugo and then deploy your public directory to your site.

15

all your case-studies get created in public.

My case studies are being created exactly where I want them, in /case-studies/. The issue is that, completely at random, sometimes they get created, sometimes they don’t, sometimes only a handful get created. I’m really grateful for you taking the time to try and help but if you’re going to give up your time, please read my issue, so you’re doing so productively. If you don’t have time to help, that’s absolutely cool.

So, this is actually not a Hugo problem. Never was.

It sounds like we’re never going to find out, at this point, as nobody actually seems interested in reading my actual issue, just talking over me and assuming I’m an idiot.

Perhaps reading the documentation carefully (and following its guidance)

I have spent two days doing this.

Aside: It might be easier to get on a learning curve with Hugo if you use a simpler setup.

I am trying to rebuild our corporate site in Hugo, which I have built in more than one SSG over the past two decades, as an experiment, to see what I learn about using Hugo to build a site of moderate complexity.

Why do you have a myriad of SCSS files that result in more than 500 CSS rules?

This is the real css from our website. It’s about 4kb of CSS, far smaller than most sites on the internet.

Why do you assign a layout to your case-studies _index.md that you then cascade, instead of putting single.htmland list.html templates in your layouts/case-studies?

This is probably a mistake. I’m learning.

And what are these &desc and *desc things doing in your description front-matter?

They’re YAML “references”, properly called “node anchors”.

And please set your baseURL to the base URL of your site. Do it now. It doesn’t do any harm with hugo server, but you’ll be very sorry if you run hugo and then deploy your publicdirectory to your site.

This is just a testcase for this forum, it’s not my live project.

16

Just to further demonstrate what I’m on about, I’ve pushed yet another commit here, demonstrating that switching _index.md to index.md has no effect on the issues I’m experiencing.

I’ve pasted the steps I took into the git commit, but i’ll paste them here as well:

chris@chris-mbp:~/Developer/testcase|the-case-studies-are-back⚡ ⇒  rm -rf public
chris@chris-mbp:~/Developer/testcase|the-case-studies-are-back⚡ ⇒  mv content/case-studies/_index.md content/case-studies/index.md
chris@chris-mbp:~/Developer/testcase|the-case-studies-are-back⚡ ⇒  hugo
Start building sites …
hugo v0.131.0+extended darwin/arm64 BuildDate=2024-08-02T09:03:48Z VendorInfo=brew


                   | EN
-------------------+-----
  Pages            | 42
  Paginator pages  |  0
  Non-page files   |  0
  Static files     |  1
  Processed images |  0
  Aliases          |  0
  Cleaned          |  0

Total in 560 ms

As you’ll see, case-studies has an index.md, guides has an _index.md, neither are output to public.

17

That’s not what you said:

With the change I suggested, all your case-studies are generated in that directory. Did you even try to change the directory structure as I suggested?

Well, what your “issue” is, was never clear (not to me, at least). I resolved the problem that only two of your case-studies appeared where you want them. You didn’t even acknowledge that but keep on complaining that nobody is interested in your issue – I actually worked on it for some time, on the weekend. Apparently, to no avail.

Which is not what I suggested. Not by a far cry. But suit yourself.

18

Rename content/index.html to content/_index.html and most of your issues are solved.

Read up on Page bundles | Hugo.

I also recommend adding “public” dir to your .gitignore file and delete it from the repo. You avoid a lot of hassel that way.

1 Like
19

Well, what your “issue” is, was never clear

Sorry, going back to my original post, I’m experiencing a collection of issues simultaneously, which, to me, seem related. As if there’s some sort of issue with the filesystem watcher. I’m genuinely not sure why people feel these aren’t clear explanations, but I’m absolutely happy to elaborate further with specifics on any of these, because I really would like this to work. From my original post:

  • only a handful of items in a large collection appearing in lists
  • changes to content items only being reflected on adding/editing/sometimes deleting an _index.md
  • changes to _defaults/baseof.html being completely ignored on some pages (when they are reflected on others)
  • Live reload not working correctly - complaining about syntax errors that have been corrected (in a one line file), even when I force-refresh the page
  • Most recently, I added a bunch of assets to static, and now nothing from content is being processed to public at all. I’ve since emptied static, rm -rf public, but still barely anything apart from my stylesheets and /index.html are being processed. I know hugo is seeing the content in content, because I can see some debug logs referring to files in there, but it’s not outputting anything.

Going back to your message:

Did you even try to change the directory structure as I suggested?

Sorry, I did actually mis-read your suggestion, I thought you were simply suggesting I switch from a leaf to a branch. I’ve now done what you asked, and, it hasn’t worked. See commit message for my console output.

I’m really, honestly, truly grateful that you’re trying to help. People on the internet sometimes seem like they’re acting in bad faith, I’m not. I’m genuinely grateful. But it only really helps me if we address the actual issue I’m having, which is basically “hugo, as a whole, is acting bonkers for me”. Stuff that previously worked suddenly stops working or changes how it works, without me taking any obvious action related to that stuff.

20

ok, let’s comment on your points with some of my experiences:

the term site setup includes everything in your project root folder and the commands used to build

additionally I think of a clean setup without having no resources and public folder. and deleted all cache content (see docs where they are)

I assume you do either hugo or hugo server one time with a clean setup. We want reproducible results, right?

I have never seen missing pages without errors in the site setup

with hugo - never seen that
with hugo server it has been usually a cache issue with the browser not reloading the pages

with hugo - never seen that
with hugo server it has been usually a cache issue with the browser not reloading the pages

with hugo - never seen that
with hugo server YES, sometimes after errors in coding hugo server cannot recover. This depends on the severity of the errors (especially go-templates in stuff called from baseof html).

In that case you will have to restart the server.

with hugo - never seen that

all that said

  • could it be that you mix these commands, eg. calling hugo with a running running server? or connect multiple browser instances to hugo server

  • also keep in mind, that hugo server is not an IDE - it eases up to check if the visual site matches the target. It’s also not a full featured web server and has it’s limitations.

  • you report many issues in one topic and constantly playing around with non related stuff or changing multiple stuff while your site or process is broken.

and finally

  • concentrate on one error start with the most basic one

  • use your 25 years of experience on how to track down and isolate errors

  • if you cannot catch it provide the reproducible example, incl. ALL steps to reproduce (fe. if you have a combination of steps.

  • describe the expected result and show the target incl all errors/warnings …

22

Starting from a clone of your original repository, ie the main branch:

for i in [a-z]*.md ; do j=`basename $i ".md"`; mkdir $j; mv $i $j/index.md ; done

resulting in

content/case-studies > tree
.
├── _index.md
├── barchester
│   └── index.md
├── chartboost
│   └── index.md
├── covea
│   └── index.md
├── deathwishcoffee
│   └── index.md
├── gbg
│   └── index.md
├── how-marmalade-insurance-improve-customer-experience-case-study
│   └── index.md
├── how-polypipe-learnt-to-benefit-from-customer-feedback
│   └── index.md
├── how-the-digital-marketing-institute-improves-net-promoter-score
│   └── index.md
├── kk-wind
│   └── index.md
├── optimus
│   └── index.md
├── philips
│   └── index.md
├── spark
│   └── index.md
├── swiftpage
│   └── index.md
├── tastecard
│   └── index.md
└── ubt
    └── index.md

Now

mv content/index.html content/_index.html

as suggested by @irkode
and hugo server produces

tree hugo-example/public/case-studies
hugo-example/public/case-studies
├── barchester
│   └── index.html
├── chartboost
│   └── index.html
├── covea
│   └── index.html
├── deathwishcoffee
│   └── index.html
├── gbg
│   └── index.html
├── how-marmalade-insurance-improve-customer-experience-case-study
│   └── index.html
├── how-polypipe-learnt-to-benefit-from-customer-feedback
│   └── index.html
├── how-the-digital-marketing-institute-improves-net-promoter-score
│   └── index.html
├── index.html
├── index.xml
├── kk-wind
│   └── index.html
├── optimus
│   └── index.html
├── philips
│   └── index.html
├── spark
│   └── index.html
├── swiftpage
│   └── index.html
├── tastecard
│   └── index.html
└── ubt
    └── index.html

If I stop the server, remove this public directory and re-run hugo server, everything gets recreated just as before.

I’d say it is all about leaf vs. branch bundles. content needs to be a branch bundle (aka _index.html instead of index.html). Similarly, case-studies must be a branch bundle (which it already is through _index.md) – but it cannot contain content files (namely your xxx.mds). You must move each md file in its on leaf bundle, i.e. a directory containing the file and possibly other things.

23

Please see the commit I linked to in my reply.

Can we try a simple acid test here: What happens when other people pull my repo and try and compile the site? Use any of the commits I’ve linked to.

Do you get case studies and guides in the public folder? (Anywhere at all in public, regardless of where).

If you get no case studies/guides output, then yes, this seems like a config/site setup bug. The same config is working the same on your computer and mine, I am being very silly, and I need to learn, which I will gladly do, because then I’ll have a deeper understanding of a tool I’m interested in.

But if you do get case studies and guides output into public, then your computer is behaving completely differently to mine, which kinda shows what I am trying to explain here, namely that — for me — hugo isn’t acting deterministically. Please, nobody take offence, I am not suggesting that this is a terrible, buggy piece of software. It is because it has such a good reputation that I’m interested in it: I am trying to explain that this well-tested, widely used piece of software is acting weirdly for me, and trying to work out why that is.

So if you don’t get case studies/guides output: cool, this is my chance to learn something, let’s look into it more.

But if you do get case studies/guides output: please can we understand that something weird is happening on my mac, I have read the manual, I have tried to debug it thoroughly, I have spent two long and painful days doing this, I’m at my wits end, and I’m reaching out for help.

If nobody here can answer the question, that is fine too. Genuinely appreciate strangers taking a look at it.