Hugo has some real usability issues... Let's address them

There are challenges with using Hugo that I think prevent us from having a larger community. Like almost every stack I’ve ever used, I have a love-hate relationship with it. I very much want to stick with Hugo, because the love is real, and I’m having success with site-building, and fast-loading websites.

But there are barriers, significant ones. The one I’m experiencing right now is simply the challenge of figuring out why I can’t create a permalink. I think I diagnosed the issue as having some sort of bundle vs. a section. But no matter how many blog posts I read on page bundles and branch bundles and permalinks etc… I find it to be confusing… and I’ve come to the conclusion that the only way I know to create a permalink is to manually place it in the front matter.

I put this post under tips and tricks, because the big tip I offer is that we need to make more explainer videos of and community-building regarding the things that are BLOCKING progress. What slows you down? What solutions have you figured out?

I had started building but I haven’t been maintaining it. (Personal note, that vaccine injury cost me my health, and that’s my current battle… I have fewer good hours in the day.)

I’d love to see a woman-friendly, newbie-friendly, diversity-friendly and usable Hugo continue to be growing access for successful developers. I’d love to see more YouTube channels, more conferences. I’ve got energy for Hugo! I don’t know any of the players, and hope that the community is welcoming someone who says: there are some real challenges halfway up the Hugo learning curve. Let’s see what we can do to identify the sticking points and help people out of them. I don’t know how many of the solutions are work-arounds (like putting url in the frontmatter) and how many are snippets, and how many are core usability issues. (Does every one of my blog titles need a different name?) In any case, for now I’m going to manually create the URL I want… and at the same time try to develop a sense of community here. I can imagine creating weekly zoom meetings, where people share a project their working on, where they ran aground, and either the solutions they found or just an open-ended how-to-fix-this question. Would anyone be interested in that?



Hi Margie, first of all … how are you ? Hope you are fine…

Nice to read such statement… as i am on the same boat. Just coming from the Jekyll lands.

As you already did (BTW, is the source code public? ) , i’m starting to buld my own Notes- Blog… as part of the learning experience. Let’s enjoy this metaexercise!.

Inspired by Usecue’s HugoCodex Project.

I discussed with them about a potential ‘Best Practices’ or just a humble / simpler approach to Hugo as a Web developement tool.

How does it sounds ‘Hugo Light’ (or uHugo - micro Hugo ? )

The naming because of the fact that we are aiming at a simpler (subset) learning curve of this Golang (Web making) framework.

Let me know about your thoughts



Thank you for responding!

When you say “How does it sounds ‘Hugo Light’ (or uHugo - micro Hugo ? )” are you asking about a proposed blog name? I can’t quite tell. To me, if I saw the phrase “Hugo Light” I would think it was a different port of Hugo, and that would strike me as a little confusing.

I think a good name would be simply “Learning Hugo” or “Hugo Best Practices” (assuming you can figure them out)…

Where is your blog? When you say you “discussed with them about a potential ‘Best Practices’…” with whom did you discuss? How did the discussion go?

I think the problem isn’t just the learning curve. I think that Hugo itself has some usability barriers… We would have much wider adoption if this weren’t the case. But if the usability issues will stay what they are… then yes, let’s do all we can to assist people (including ourselves!) on the learning curve. Either way, I look forward to seeing your blog when you share it.

Why did you switch from Jekyll? Have you been happy with the switch? What barriers have you encountered?


1 Like

Personally I had some issues with approachability of the Hugo documentation, but that may be my own fault.

I took me a while to kind of grok how Hugo approaches your templates, what applies where etc. If that makes sense? Which seems to be a step missing in the current docs. The blog I found that helped me the best was one that didn’t use a default theme, but made a simple and approachable baseof, single and list template. Only then did the Hugo documentation start to make sense for me.

1 Like

Trust me, they’re not your fault. The documentation is a sore point for many people.


I mean, they’re not bad, once you get the hang of it, everything is well documented, it’s just that timeframe before you get into it isn’t covered in the official docs or tutorial links from the homepage.

Depending on what “bad” could mean. They’re written from the perspective of someone who knows how it all works, not from the perspective of someone who needs to learn that. E.g. the chapter on assets: They tell you, how to manage assets before explaining what they are and why you’d perhaps need them and for what. That is maybe not “bad” per se, but it is “bad” in the sense that it is not appropriate for a particular audience. Namely those wanting to learn about Hugo.


Hey Margie with the switch ? Well. I don’t measure my workflow in " happiness units"… as i used to do.
I just let flow my intuitive side. Is fine as long as it does the job i want to accomplish.

I just wanted to have a second Static Site Generator (SSG) for

As long as i’m ussing JAMStack platforms for hosting and editing backend for my costumers now, building time is an important factor for me.

Hugo builds much faster than Jekyll.

my 2 cents ?

PS: i’ll share my blog once it’s ready… :slight_smile:

I’ve had similar issues, getting my head round weird syntax issues and capitalisation in params/menus was a HUGE headache, I’ve started up a community discord with the intent of making the learning curve less punishing on small stuff like this, the aim is to be an informal level of support compared the the discourse.

1 Like