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.


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.

1 Like

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

Hi @mroswell

I am a beginner with Hugo and I was wondering why there aren’t new blogs, video tutorials for Hugo which is one of the best SSG. I think Hugo community have came to a slow decline it gain huge popularity and then it just stayed with small community growth. And somehow the content creators are not encouraged to back Hugo. And I think main reason is access to the knowledge and transparency.

but there is another side to it if you check on the developer side of this, a golang developer friend told me that he find Hugo documentation clear and really easy to understand. So I suppose there are 2 levels to Hugo and it is not for the people with limited golang or in general lower level of development knowledge. it is not as easy to learn as gatsby for example.

Anyways I suggested to provide an option to back Hugo content creators of my choice directly via Hugo platform but as of today I haven’t heard anything back. so I suppose it is not there priority and the general mentality is take it or leave it which is disappointing and doesn’t give me enough to stand behind Hugo at this time and I think it explain why there aren’t many sponsors or content creators behind hugo :slight_smile:

1 Like

This is the general vibe I get with Hugo, especially from some replies in this forum from some moderators and users. I remember when moving to Jekyll, the tutorials and documentation were diverse and easy to understand that I asked one question only in the Jekyll forum! For Hugo, I asked multiple questions here, reddit, discord and stack overflow to get answers. Spending over 100 hours to move the site was frustrating and I almost gave up.

1 Like

hi @anon44707125,

trust me once you go past this frustrating stage where you don’t know how Hugo works etc. you will end up loving it. but yes there are many issues that you will never find the answer to reading through documents or searching online for example this

{{ $titleFirst := split .Title "" | first 1 }} 
# this result in C
{{ $titleFirst := split .Title " " | first 1 }} 
# this result in Company
  1. access to knowledge for beginners is the main issue I see with hugo.
  2. lack of new Hugo tutorials blogs is the second main issue

documentation is not search friendly for example the word “pre” which can be used in the menu pre: gives no clue to what it is and if you need to use this you will never easily find it exist.

I also try to see if I can help in a way to highlight some issues to maybe get more Hugo support by making this post at time I posted Hugo had 67-68 public sponsors on GitHub 2 weeks later today there are only 64. so I see it loosing sponsors 2/week cant say if this is a pattern for long time or just happened now.

most of the Hugo related questions are really basic and mostly repeated the reason being not sufficient beginner friendly uptodate documentation. i made this post to suggest some dummies/ beginner discussions but that was also ignored.

so to sum up out of all the SSG I have tried Hugo seems to be the best option here until I see some new option. learning is really difficult in the beginning comparing to other tools, any recommendations or feedback is usually ignored or aggressively silenced.

So I can say I love Hugo for the simplicity and speed and I hate Hugo for lack of uptodate easy to access knowledge.

1 Like

TBH, I like it now than the beginning, but far from loving it. My case was a simple blog. I will see in future when I try to add an e-commerce shop if the frustration will be less.

And this is a glaring problem. Cue this example of me looking for “subsection” only to find it is called “nested section”.

Someone mentioned how the documentation is scattered across different sections. Hence, a need for a new approach to documentation. Last I checked, the small team Hugo has (mainly volunteers) means such issues are always put in the back-burner.

I have spent hours in this forum and these instances come up several times, but the moderators have been more aggressive in recent years than in the past when the community was small.

I tried Hugo for the fast build speeds, otherwise, I had no problem with Jekyll per se. But it being a single binary is also something I like. Perhaps the more I interact with it, I might find other things I like. The documentation is what I hate the most and also having to result to trial and error to get things done.

Just a note


My experience has been frustrating in the beginning. The docs are references, not tutorials. Trial, error, patching, rinse, repeat. My site is up now, but the way to get here was a nightmare! However, I appreciate how versatile Hugo is! The team has put effort into it, and I hope the same will be applied to the docs.