I’ve been a Hugo aficionado and small-scale evangelist for many years.
But a while ago a Hugo update broke my site/theme and I simply couldn’t fix it.
Hugo’s much-touted documentation has become almost impossible to make sense of IMHO, despite the relentless work by a dedicated team.
The sheer volume of posts asking for help in this forum illustrates IMHO the issue I’m addressing. The diversity of open issues is beyond comprehension and a casual topic browser would come away with the impression that Hugo is insanely difficult to operate.
And through regular web searches over the years related to the use of Hugo, I’ve noticed that I’m definitely not the only one having become somewhat disenchanted with Hugo’s growing complexity.
I apologise beforehand to anyone who feels offended by the above.
Please note that I’m not bashing Hugo or showing disrespect to all those contributing.
But I’m certain that there’s a growing sense of bewilderment over the years amongst its user base.
Of course Hugo has grown and it is complex, as it has been in active development since 2014.
As someone who is not developing Hugo but who has spent a considerable amount of time contributing to the Hugo Forum as well as being a former maintainer of the Hugo Themes Showcase, I know first hand that when things break down, we do issue detailed instructions about fixing the problem.
Also please note that things do not break that often. Typically there is an advance deprecation warning, but sometimes things break upstream or due to human error.
Usually one can find a solution to a problem through this forum and the Requesting Help guidelines do contain useful info for anyone seeking help.
As for the Documentation of course one needs to invest time.
On a side note, currently I am learning French and it feels like I am in elementary school again.
I couldn’t possibly expect myself to read Victor Hugo’s Les Misérables in the original without spending the prerequisite time.
That or that Hugo has become increasingly popular.
I’m not saying that you are wrong, and you’re of course right about the documentation not being good enough. But my 50 cents on this, biased as that is, is that most of the “added stuff” is totally optional – you can still treat Hugo as it was in Hugo 0.16.
Which meant, I needed to look at the source code of the theme, figure out the project structure, copy-paste all the folder names and put my override of index.html there. Which, BTW magically overrides it. This whole magic thing is BS and I am being strongly opinionated here.
For anyone who approach concept of objects and object oriented programming, (by just less than 3 kilometers away), this is pretty simple and straightforward, and just what makes one of the Hugo’s beauty. Reminds me my old time with zope.org.
So when someone is bashing one of the strength of a product, I guess something is not totally right on his side.
Use a theme as is if you are total noob. But if you want to make some change, at least, please try to understand the philosophy of your product.
My Mazda MX-5 is a really bad car because after 3 years of happy driving, I couldn’t make some changes in the engine.
Hugo itself is as complex as it’s useful, so I’m not going to say anything about that. It’s the process from beginner to expert that is complex.
I picked up Hugo a few months ago and my learning curve was steep. I never found the docs completely useful. There’s a lot of information, but I find the factorization a little awkward. For example, If you search info about shortcodes, you’ll find three pages:
Of course, they all serve different purposes and it’s logical to divide them like that, but in practice I had to go back and forth between them. I still can’t put my finger on it, but I think that there’s plenty of room for improvement. I promise I’ll contribute to the docs some day.
I agree about the docs, and we should do an overhaul (I have waited until we get some “data from pages support”, which would allow to auto generate all the template funcs signatures etc.). I find that it works now best as a “lookup service” (I use the search a lot to look for specific things), but that requires that you know what to look for.
I don’t know if Hugo has become ‘too complex’, but it has for sure become more complex in the last year(s).
The last release (0.78.0) even added "js.Build fully supports the virtual union filesystem in Hugo Modules.", which is a short sentence with three terms that I don’t understand.
But I don’t know if this is a problem. For people that need complex features it’s probably quite useful. And for me it makes no difference since I don’t use those features.
I am worried though about the experience for new users. Beginners that run into issues with a theme have a hard time troubleshooting (which is also the fault of theme creators for adding complexity). Learning Hugo is not easy because there’s a lot of material to go through.
Several weeks ago I read a Hacker News discussion that had love for Hugo, but also people that even hated working with Hugo. Most of the complaints were about the template language and the complexity, or a combination of both.
A couple months ago we also had the JAMStack survey. While there were valid concerns about the sample demographics, it showed that Hugo users that participated in the survey weren’t as satisfied as Svelte, Nuxt, Next, 11ty, Vue, Gatsby, or React users.
If the Hugo team would be bigger, it would be awesome if we could have something like Go’s developer surveys to learn what pain points there are.
But from what I understand most of the Hugo work is already done by only a few individuals in their free time. So while I agree that parts of Hugo are too complex, I don’t see a solution without asking for even more from the people that already gave us so much.
Thank you for your contributions and insights! I realise that I’m addressing a sensitive issue here.
@ jura: I sense a kindred spirit in this regard.
A little more about where I’m coming from: I’m Joe User. No ‘real’ coding experience (other than HTML and CSS) but willing to learn elementary stuff that helps me wrangle Hugo to a certain degree. That said: I know that Hugo using friends of mine also simply stopped installing Hugo updates because doing so broke their setup. Hugo updates that didn’t bring us anything useful, just bitter frustration. We couldn’t figure out what we’d done wrong. Most likely we’re using a theme that has been neglected and will no longer comply with Hugo’s latest & greatest. But some time ago my OS version couldn’t deal with the latest version of Go. Bep was able at the time to help me and identify an otherwise extremely obtuse and unhelpful error code.
I can’t, for the life of me, understand most of the new features or changes that have been implemented in Hugo and have failed to do so for a long time. The safest thing to do seems to me to stop updating out of fear of breaking something. And I think I’m not alone in that respect, far from it. I’ve also followed the Hacker News topics dealing with SSG’s and Hugo isn’t always mentioned favourably anymore, like it used to be. That saddens me but it’s the harsh reality. Another Hacker News discussion with strong opinions pro & contra.
With regard to writing documentation: I don’t think I’m telling anything new when I state that writing code and writing documentation (user manual) are 2 very different disciplines. IMHO very few gifted coders are able to use the ELI5 method when interacting with Joe User. Luckily, this forum is able to provide solace when the official documentation has been found lacking. But in doing so this forum has become a source of documentation addenda that is not only very hard to search but has not (completely) been incorporated in the official documentation.
I’d like to stress again that I have the greatest respect for all those who are working on helping Hugo forward and are willing to help its users in this forum with their problems. I’m grateful for their selfless dedication and willingness to help others.
I am certain that all spoken languages are imperfect, but English can be particularly annoying. For example, in English, these four words are pronounced in the same way but have different meanings: right, rite, wright, and write.
Some words have a different meaning or connotation depending on context. Two examples of this are the words complex and complicated. A common misconception:
COMPLEX = COMPLICATED
COMPLICATED = BAD
Therefore, COMPLEX = BAD
The first two are false assertions, resulting in a false conclusion.
There is nothing inherently “bad” about complex or complicated systems. However, either can be overwhelming if not carefully presented. I believe we have a documentation challenge, and I’ve been pondering this for several months. My thoughts:
Divide the documentation into four parts: tutorials, how-to guides, reference, and discussion. To understand why this is important, see this 30 minute presentation by Daniele Procida. The punchline:
I can’t agree more. I always wanted to contribute, but actuel documentation has some strong guidelines to keep is synthetic, clear, and not obfuscated with examples. And that’s fine by me, as long I take it as what Daniele calls Reference.
I also understand that the really rapid dev state, all the new features added at great rythm make it difficult to make it differently.
So my give back is trying responses in this forum. I guess this forum covers really well the discussions part.
I also try to make some “tip/trick” posts because it is the only usefull place to do it (and the outside world do not need an other personal clever blog).
So, personally i could participate in tutorials or how-to if there where an official section for that. No pb (except it will need some grammar post-proofing ).
This will not be possible without a clear guidance/guidelines about how Bep’s and gang want it to be done/organized.
But I’m willing to give help for defining what could be usefull sections/items in how-to-tutorials.
The caveat for this is : I saw millions of this “I’ll help” failing for more reasons, but if, somehow, we can have a view of what could be usefull and how it could be organized, it will be possible for us non-go coders to help on the doc side.
I saw what bep said about pages from data, so may be he already has the full picture in mind for the documentation he/gang would like to see ?
In my previous post I included a screen capture from a presentation by Daniele Procida. It occurred to me that I had not asked for his permission, so I sent him a short note with a link to this topic. He graciously responded, granting permission and providing additional information.
This thread reminds me of reading this discussion as well as this from a while back.
Short of a complete overhaul of the docs site, one potential option would be to curate a “team-vetted” selection of How To guides / Tutorials / etc that already exist in the wild, and maybe link to them from a special section within the docs.
But, of course, the question is always “Who would commit to doing the work?”
I always keep Hugo up to date with the latest, and if there are any breaking changes, I just look them up or ask about them. I am notoriously stubborn and headstrong etc.
A little more about where I’m coming from: I’m Joe User. No ‘real’ coding experience (other than HTML and CSS) but willing to learn elementary stuff that helps me wrangle Hugo to a certain degree.
Perhaps for myself, being a software engineer makes it easy. I like Hugo. I enjoy using it. I like the structure. Somethings could be better, sure, but that’s anything.
Though, the question is, are static site generators for non developers? I mean we can make front-ends for them all day long like Netlify and etc. but at the end of the day, IMHO you can’t be a non coder and use static site engines effectively/efficiently, without mucking around in code of templates or Hugo upstream itself.
I’ve discovered almost all static site generators require you to be a developer, unless you’re just using other people’s themes and code, in which case, yes, you’re dependent on them to update any changes they need to make, and you can’t really complain about Hugo.
I’m sure there are many who will disagree with me.
And if we can have some clear guidelines about the formalism/structure needed for those sections to remains coherent, it would help us proposing some PR.
it even can lead at some step to some official frontmatter/partials we can use.
Hugo’s complexity is under the hood – hidden in a single binary.
If you use almost any other SSG you will probably end up in a dependency hell – one hell for each web project.
I switched to Hugo years ago because Ruby gem packages regularly were not compatible with each other as soon as one of them was updated. It always took a long time to figure out which package caused the error, and then to switch back to and stick to a specific version.
With Hugo everything just always works without any other installation.
I’ve only been using Hugo for less than a year. I’m in no way connected to IT professionally, I’m not a software developer by trade, and I got hit by the learning curve and the idiosyncrasies of the documentation more than once. Yet I think there are several things that need to be taken into account when discussing Hugo’s complexity and/or user-unfriendliness/steep learning curve:
Developing complex web sites is not easy. A lot of people make it their trade, and anyone can hire those professionals and pay money (sometimes good money) for a web site. Hugo is a tool that allows you to develop fairly complicated websites by yourself, but requires you to learn some things to do that sucessfully. Make some effort. If developing a web site was something that didn’t require any effort, those web developers would end up in other trades, you know.
99% of the time when I see someone complaining about Hugo being compicated and unfriendly the real story is that someone used a complex theme that either got abandoned or doesn’t suit the needs any longer. The theme’s author did most of the cognitive work for you; it takes much less effort to use a theme than to build a nice website from scratch. If you want to do more than the author intended with the theme, you need to learn more about how Hugo and themes work. Yeah, tough.
I ended up using a theme that the author abandoned, and I’ve had to fix it several times already to make it work with newer versions of Hugo. I made pull requests with the fixes, but the author never showed up to merge those. The stale repository is out there, the issues are documented, the fixes are documented as pull requests, yet every month someone opens an issue in the theme repository about the theme not working. They don’t even bother searching for the issue where the problem is described and the fixes are referenced…
Hugo is a static site generator. That means Hugo’s output is a bunch of static pages. Static pages can’t really be broken or abused (the server that serves them can, but that’s another story). There’s no security threat whatsoever in using an older version of Hugo. If it works for you, and you don’t want to spend the cognitive effort required of you to move to a newer version of Hugo, you can safely use an older one. Yes, you won’t get the latest and greatest features that way. Tough life.
Hugo is open source. Hugo’s documentation is open source. If you think it’s a little inadequate, you can help fix it. Not everyone is a programmer enough to fix Hugo, but you can help fix the documentation if you want. The little team behind Hugo welcomes every useful contribution and helps you to do it properly if this is your first time, don’t be afraid. If you feel like chipping in, please do!
If, despite all the things I’ve listed above, you still feel like Hugo failed your expectations and don’t want to deal with Hugo anymore, it’s sad, and I think I’m speaking for a big part of the community when I say we’re sorry to lose every member of the community and we’re sorry to see you go. However, as far as I know, you can get a full refund — yes, all the money you’ve paid for Hugo will be returned to you, every last cent! Isn’t that awesome?
The above observation is at the very heart of the issue raised in this topic.
That is why we direct people to the Requesting Help guidelines, that have been written by several contributors of this forum.
Also we did spend quite a bit of time extending the README of the Hugo Themes repository to offer detailed advice for theme submissions, but still we did see the same issues pop-up again and again because people never actually read the README.
For some reason many people have specific ideas about how certain things are supposed to work. Not everyone is willing to invest the time and get out of their way to learn a different tool that is not quite like the rest.
I agree with every word @jmooring said. Every jot and tittle.
Thanks, Joe, for the great links to Daniele Procida’s content. I’ve been pondering the same issues off and on for a while but hadn’t done any real research. Daniele’s presentation and the progressive disclosure approach captures everything that’s been rolling around in my head. Very helpful.
In my humble opinion, Hugo would benefit from two main new additions:
Plugin support and development
Integrated “lite” version.
Allow me to wonder you by exploring these two wonderful ideas.
Sit on a newspaper first, because by the time I finish this, I promise you: you
All right, here we go.
Plugins is what makes Wordpress big. Once you have a system and clear guidelines to develop plugins, developers can create and sell plugins cutting down 90% of the footwork for newcomers.
That takes me to the second point; the “lite” version. Hugo needs a version for the casual blogger. Someone who wants to publish a blog or small CV site should be able to do so without having to read one page of the documentation. As it is, to be able to do the simplest blog, you have to read at least half of the docs digging for the answer. Yes, we have the “Getting Started Guide” where you can be “up and running with Hugo in 2 minutes”, but people need to be able to customize their project. That doesn’t happens with Hugo, unless you want to spend the weekend reading the docs.
Plugins would take care of that issue.
Also, as it is, wordpress ===> Start small, customize to make something huge.
Hugo is the other way around. You start big and have to push your way around to get something small.
The blog post the OP linked explains it quite well. You can’t be up and running with Hugo in 2 minutes. There’s a half truth in that statement.
Hugo is destined to become something only more knowledgeable devs use, and that’s all right.
It will be fun to see newcomers have their way with it too.
