Has Hugo become too complex?

[Peter_030]

You make a few noteworthy observations.

Allow me to quote from here - the author is a fan of SSGs and Hugo

In one of my past Work Lives, I wrote user manuals for fax machines. (Obviously, this was a long time ago.) Our team prided ourselves on “writing for Grandma,” as we put it then, because our products were bought by people of all ages and experience levels.[5] Thus, I am acutely aware how far short SSGs’ docs fall when it comes to being understandable by people outside the narrow circle of their own community, and sometimes even some within it.

and

At some point, the SSG folks will have to decide whether they do indeed want to maintain their role as Merlins rather than making SSGs accessible to ordinary users, particularly in corporate life. I mean, WordPress is a God-awful, performance-eating, security-defying thing—but at least your average Joe or Jane, and most notably your average Joe or Jane in corporate settings that aren’t going to hire dev help for them, can use it. Try that with any SSG.

and from a footnote here

Of course, you should also check the official Hugo documentation, but be forewarned that it’s clearly intended for a more technically oriented audience

FWIW, and with the greatest respect to those who have replied above, I find their comments mostly reflecting the issue at hand: coders/devs talking amongst themselves where jargon is a regular pattern of speech. It’s like I’m brosing Hacker News comments. The aforementioned ELI5 principle seems an almost foreign concept, something to be eschewed for reasons that escape me.

I’ll reiterate ad nauseam: my OP isn’t intended to bash Hugo or disrespect its devs and the general community. Far from it. I want Hugo to prosper and reach a wider audience. IMHO it’s necessary to reflect on an issue that hasn’t been addressed with some urgency during its rise to prominence: make Hugo better usable for Joe User. For the rest of us, so to speak.

[nekr0z]

@Peter_030

I want Hugo to prosper and reach a wider audience.

Don’t we all? But we can’t expect @bep deal with that single-handedly, can we? Not with the number of the open issues in the repository…

That person you quote from claims to love Hugo, claims to see the big issue with its documentation, and claims to have impressive background in writing documentation, so obviously is capable of helping fix that issue, at least to some extent. It’s really great to have someone like that on board as an active member of the community, I’m sure he contributed a lot to the hugoDocs repository since he wrote that piece, let me just check… Oh, yeah, nevermind.

@Peter_030

IMHO it’s necessary to reflect on an issue […]

It isn’t. What is actually necessary is:

1. identify the issue (you already kind of did that),
2. find someone who knows how to fix it and cares enough about it to share the knowledge,
3. find someone who can do what needs to be done based on the abovementioned knowledge (not necessarily the same person as above) and cares enough to do it for the community.

You see, there are no SSG folks up there on Olympus Mountain doing their coder/devs things without caring much about Joe User. It’s just people who care enough to dedicate their spare time. Everybody is welcome to join. Every contribution matters.

[Javier_Cabrera]

@nekr0z

Hugo modules

Yeah, I’ve seen that.

Modules…this is precisely why some people find Hugo difficult.

Why not call the damn thing Plugins? Why “Modules”? Someone coming from WordPress sees the docs and–well, you know what? Crystal clear. Newcomers are not Hugo’s primary audience. Maybe they used to be, but not anymore.

That’s just an opinion, btw. So let’s roll with Modules.

I get it. Open Source. Thank you, really. Not complaining to @bep or anything. Great guy. The best.

Part of helping an open-source project is assisting the devs with the docs, yes. You are right. But, creating a welcoming environment for people to make suggestions and, God forbid, offer a few comments about where things are heading is also part of managing an open-source project.

If every person who tries to speak up needs to first show some badge of honor for having answered forum posts or updated the docs, this will go stall sooner than later.

P.S: I made a plugin for Hugo, by the way. Before the Modules update happened. Gave it away for free, Github and all. Not a single mention in the forums about the plugin (sorry, “module”). There is literally zero support for plugin devs. That also needs to change.

What page from the doc should I update before I can voice my opinion here again?

[Javier_Cabrera]

@nekr0z

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?

That is an extremely rotten attitude to be proud of while helping open source projects reach wider audiences. The Hugo elitism has begun.

[nekr0z]

@Javier_Cabrera

Why not call the damn thing Plugins?

Because they don’t plug into Hugo. They’re building bricks that you can use to build your website, well, more like building sections, not individual bricks… Wait, there was a word for such pre-built sections of a building, what was that? Ah! “Modules”!

@Javier_Cabrera

Someone coming from Wordpress sees the docs […]

It may come as a surprise, but Hugo is not Wordpress. It’s not even a direct competitor to Wordpress. Yes, both can be used to build a personal (or not too personal) website, but that’s all they have in common. Different philosophies, different approaches, different means for different goals.

I totally understand the people that used to drive a pickup truck and get confused seeing no steering wheel, but as long as they finally accept the fact that they sit on a motorcycle having the trottle instead of the gas pedal actually does start making sense. And yes, this thing goes much faster and is much easier to handle in heavy traffic. No, you don’t get to haul your new furniture from Ikea on it, sorry; you could, but please don’t.

[Javier_Cabrera]

@nekr0z

I totally understand the people that used to drive a pickup truck and get confused seeing no steering wheel, but as long as they finally accept the fact that they sit on a motorcycle having the trottle instead of the gas pedal actually does start making sense. And yes, this thing goes much faster and is much easier to handle in heavy traffic. No, you don’t get to haul your new furniture from Ikea on it, sorry; you could, but please don’t.

You are right, this is nothing like Wordpress.

They have class over there. They don’t threat newcomers as idiots who should go away.

I regret the moment I came across Hugo. This thread stinks to coder elitism.

[bep]

@Javier_Cabrera

Why not call the damn thing Plugins? Why “Modules”?

Because “plugin” has a lots of meanings that’s not covered. Besides, we discussed the name for weeks, and I don’t remember anyone bringing up that word.

[Grob]

@Javier_Cabrera

I regret the moment I came across Hugo. This thread stinks to coder elitism.

This should not be commented – anyway:

I am totally fascinated that so many people invest so much time, effort and knowledge – mostly in their free time.

I am not a programmer, but understanding Hugo is feasible. Hugo’s complexity is rather functionality . All in all I prefer generating a slim website with a super fast single binary SSG over dozens of MB of PHP scripts and plugins or tens of thousands of JS files. But it’s a matter of taste.

When I read some GitHub issues I sometimes don’t even understand what the guys are talking about. Programming is just not my profession. But this is not coder elitism – it’s just necessary technical vocabulary.

Hugo is a generous offer. If it is not the right instrument for you you don’t have to use it.

---

So – thank you very, very much, guys.

[cmlnet]

Just to throw in my 50 cents:

Comparison with Wordpress

Coming from Wordpress and being not an developer I really appreciate that there are no plugins for Hugo.

Sure, you have thousands of plugins for Wordpress and you can find a couple for every use case. But, they come also with problems (code quality, maintenance, compatibility issue with each other, …) or caveats (premium). In the end, many of these plugins will probably remain black boxes for the average user and she/he has to trust the plugin authors.

With Hugo there are few out of the box solutions, but that has the advantage that I know what a module or shortcode does. I must no longer trust a black box.

Additionally, there are things where I find Hugo much easier then Wordpress. For example, I found creating and maintaining a multilingual site with Wordpress always very hard and frustrating.

Docs

I like the documentation. Sure it could be better with more explanations, examples and guides. But I use it mainly as reference book and in that respect the docs work very well for me.

Community

I always found the community in this forum welcoming and friendly. Sometime the answers might be a bit harsh, but everybody has a bad day from time to time…

[mr-karan]

Hey. Author of the blog the OP mentioned in their post.

Firstly, Hugo is awesome and there’s no doubt about it. I’ve used Hugo for my personal website since 2 years and I really like how blazingly fast it is to render the pages and comes with no dependencies.

change, at least, please try to understand the philosophy of your product.

However, at this stage, all I care about is getting my blog up and writing new posts. I don’t wanna sound rude but as an end user, why should I care about the “philosophy” of a static site generator? I just wanna generate some HTML files. I won’t re-iterate my problems with doing them with Hugo but

Use a theme as is if you are total noob

Looks like you didn’t read and jumped the gun quickly. Happy to be a noob if making changes to a blog requires PhD in the art of static site generation.

Cheers.

P.S. I like Hugo very much for the things it offers. Not every tool offers everything for every user and similarly not every user has the bandwidth to contribute to the project. So, yes, while you can argue that Hugo is OSS and I should not feel entitled (which I am aware of, BTW), I also don’t have any obligations to be stuck with it. I posted my experience with it, maybe someone will find it useful, you may not.

[jsonbecker]

Hugo is complex. It’s serving a lot of use cases and is quite mature. The best thing I ever did was decide to build my theme from scratch starting with the barest of blank themes. That allowed me to build up my “just enough” knowledge of Hugo and how it works to do anything I want with my site.

I think there are two very large challenges with Hugo, one which is solvable, and one which is not.

1. Users who bother with a tool like Hugo want to maintain their own site and customize things. They are, by definition, going to have a bunch of “long tail” desires. They don’t want something that can just be created on any of the out of the box ways to get a website. Of course, customization on the long tail is the hardest thing to do, and many of these users are not going to come to Hugo as Go experts or web programmers. I think the path to dissatisfaction in this category is “I will use this very complex theme but want to change these 7 things about it and that should be easy.” I’m not sure that this can ever be easy, but one way to help this would be for the community to get good and specific about best-practices when writing themes, make it easier to understand as a casual theme author how to make things customizable in a way that’s facile for users, and possibly even note in the theme gallery those themes that adhere to those practice.

2. Following on the theme of best practices, I think that it can be quite hard as a first time reader of the docs to know what they are, or even what choices are before you. This is the part where Hugo lacks coherent tutorials, and instead have pretty ok 85% or so coverage docs. There aren’t great resources about say, using the {{ baseof.html }} template and why you might want to use that. I learned about it years after that came out and it greatly simplified my work. That’s a silly example, but ultimately, I think that just having to look up the template look up order doesn’t really help me understand when and how I may want to do certain abstractions.

So I guess I think that the best path on both problems is to provide tutorial materials that keep up with “this is the best way to do this common task in modern Hugo.” That’s what a good web framework does— here’s how to build a demo app that touches all the main concepts, in a way that teaches the main concepts, and that is kept up to date with the best practices the community has adopted. Everything else is just API documentation.

[Peter_030]

I’ve found a related (locked) discussion Comprehensive hugo tutorial for beginners? that has (at the time) drawn some attention and participation over a longer period.
I took the time browsing that discussion and found it to be an illuminating read. I confess to not having been able to find out whether the issues raised there have meanwhile been addressed but I fear some, if not many, may still be relevant.

On a side note: it saddens me to find that my opinion has ruffled some feathers. I’ve posted a few questions when I started out with Hugo in late 2014, over at the now-defunct Google Groups repository. I’ve found Hugo illuminati to be extremely helpful and managed to get up & running more or less as advertised. I’m convinced this forum reflects that attitude to an even greater extent, from what I’ve been able to see over the years. Rest assured that I have nothing but the greatest respect for all who selflessly dedicate their valuable time and share their experience and knowledge, here and elsewhere.

[nekr0z]

@Javier_Cabrera

What page from the doc should I update before I can voice my opinion here again?

You can totally voice your opinion here, no one is shutting you down. I think you are wrong and your opinion is based on the wrong assumptions, but that’s my personal opinion.

@Javier_Cabrera

They don’t threat newcomers as idiots who should go away.

Neither do we, and the awesome support newcomers get on this very forum, with people endlessly answering the same basic questions for those too lazy to use the search button, is quite the evidence of that. I mean, another question about the difference between {{- ... -}} and {{ ... }} got answered last night, with the actual answer and a link to detailed information (not this one, mind you) — how much more welcoming can a community realistically be?!

@Javier_Cabrera

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.

No, you don’t. Download a theme of your liking, add it to the config, and you’re done. Simple, effective, fast, no technical knowledge required, a huge number of step-by-step guides out there, including the ones in every theme’s “readme” file.

@Javier_Cabrera

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.

Yes, to customize a site (or a theme) deeply you need to know more about how Hugo works. The more you want to customize, the more you need to know and understand. The good thing is you can customize file by file, line by line, in small steps. I agree that at the moment the transition between “take a theme, add content, done” and “let’s add mermaid diagrams as previews for all the posts” is rather steep, but that’s what Hugo modules will hopefully be very useful for. Also, a lot depends on the theme; hacking on something minimalistic like hyde hyde is a lot easier than hacking on a monstrosity like LoveIt that has an example config.toml longer than 500 lines (but then again, that amount of options allows for more customization without actually hacking into the theme).

@Javier_Cabrera

I made a plugin for Hugo, by the way. Gave it away for free, Github and all.

Great! Thank you for contributing to the community!

@Javier_Cabrera

Not a single mention in the forums about the plugin (sorry, “module”).

Sorry, I don’t quite understand what you are trying to say here. Who should have mentioned it and how?

@Javier_Cabrera

There is literally zero support for plugin devs. That also needs to change.

Perhaps it does. And perhaps it will. Hugo modules is quite a recent development, hasn’t quite caught on yet. That being said, who — in your opinion — should be doing that? And in what ways exactly?

@Javier_Cabrera

while helping open source projects reach wider audiences

Let me be clear: while I would love to see Hugo reach wider audiences (because it can potentially attract developers and sponsors), I don’t think this should be the primary goal for Hugo. Againg, that’s my personal opinion (which should go without saying, but looks like it doesn’t always), but I think the primary goal should be developing an awesome piece of software that does its job well. I’m not saying activities other than the software development are not worth the effort and should not be bothered with, quite the opposite! Documentation, community building, PR, education — everything is valuable, for sure, and if anyone feels like contributing to those and any other areas, it’s very welcome indeed. But the very idea of limiting functionality and flexibility to facilitate easier onboarding is simply ridiculous and shouldn’t even be seriously considered.

@Peter_030

On a side note: it saddens me to find that my opinion has ruffled some feathers.

I don’t think there’s a reson to be sad, honestly. Hugo is a work in progress (despite being awesome enough to be used in production by many people and businesses) and Hugo documentation is even more so (despite being adequate enough for lots of current users to learn how to use Hugo). Emotions are a powerful way to influence people’s behaviour, and if emotions in this thread push one person to make one thing (be it as big as a tutorial article or as little as a one-symbol commit to docs fixing a typo) that benefits the community and the project, it was all worth it.

[bep]

I saw some note in the referenced blog post about that other static site generator (Lola?) where one of the key points was that the maintainer refused to add a given feature because it would add complexity.

The features I add to Hugo or the bugs I fixes, those are stuff that I need fixed. There are certain things I find interesting on the technical level, but mostly it’s because I need it. That is egoism more than anything.

And you may argue that some of the features added to Hugo has added some complexity, but that’s because some projects require more than the basics. If Hugo didnt’t have a solid support for TailwindCSS and JS bundling etc., then I would not use it. And if I wasn’t using it, I would not maintain it and spend time here answering questions.

And I would claim that lots of the building blocks added recently (modules, unified file system with fairly powerful mount support etc., pretty great error messages (even in browser)…) is helping with the simplicity. They may look complex in all the details, but surely simpler if we had a better story for solid starters and themes and documentation. We certainly have a much greater potential for simplicity than many of the JS alternatives, which I think is much better at this (starters and documentation) than us.

And to those complaining about this forum, I suggest you take a spin reading some Reddit threads. No forum is perfect, but I find this forum to be refreshingly helpful and responsive and mostly polite and respectful.

[bep]

@bep

The features I add to Hugo or the bugs I fixes, those are stuff that I need fixed. There are certain things I find interesting on the technical level, but mostly it’s because I need it . That is egoism more than anything.

That statement is overly simplified, but I hope you get the drift. I don’t mind helping out with stuff that is not isn’t in that category, but … Luckily I have a very broad area of interest/needs.

[cookcomm]

Yes, I am giving up on Hugo. All. I needed was a website I could start with. But Hugo examples always end with server asking for various layout files or resource links which newcomer has no way to understand. Thus, I can never see a website. Sorry if I offend.

[HughP]

It took me a few weeks and tries to see how modules worked, and then it dawned on me: These modules can be functionally equivalent to wordpress plugins… made me really happy…

[Javier_Cabrera]

@cmlnet

I always found the community in this forum welcoming and friendly. Sometime the answers might be a bit harsh, but everybody has a bad day from time to time…

Most likely the norm. Hugo is a great tool. Kudos to everyone involved.

I’ve made a SEO plugin (sorry… “Module-ish”), called Victor Hugo, a personal tool to log people in, called Edgar , a MediaWiki template, which looks and MUCH faster and better than MediaWiki, dark mode and all, a personal website and a magazine.
So I’ve been around.

Again: amazing tool. Fast, easy to use once you get the hang of it, and very versatile.

Still, to this day, I have yet to see the welcoming and friendly part of the community you are talking about. Aside from a few gentlemen, most answers are spat down to people. Some can ignore it, to certain extent, others go away.

This might be an unpopular opinion, but then again, any question or suggestion becomes an unpopular opinion around here. I’ve grown to accept it as a “well, it’s one of those things”.

[divinerites]

@Javier_Cabrera

Still, to this day, I have yet to see the welcoming and friendly part of the community

Sorry, tried it (SEO) but never could make it works (i do not have blog pages).
And for your other work, i never could find a repository.

[bwintx]

That person you quote from claims to love Hugo, claims to see the big issue with its documentation, and claims to have impressive background in writing documentation, so obviously is capable of helping fix that issue, at least to some extent. It’s really great to have someone like that on board as an active member of the community, I’m sure he contributed a lot to the hugoDocs repository since he wrote that piece, let me just check… Oh, yeah, nevermind.

My ears are burning. Getting in before this thread is locked… (And, no, my docs-writing experience is by no means “impressive.” Would that it were.) The aforementioned post containing the comments with which you took issue is from July, 2019. Ever since I wrote that post, I actually have given many thoughts to pitching in and helping in the way to which you’re referring. What has always stopped me is the realization that those items whose documentation needs the most help require me to know far more than I do, or have time to learn, about the fine points (and/or more complex parts) of Hugo.

Finally: my original comments that you mentioned were intended only as constructive criticism but, if your observations here are any guide, it appears they offended the Hugo community, instead; and, for that, I apologize. I assure you I meant no harm.