Has Hugo become too complex?

24

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?

1 Like
25

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

2 Likes
26

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”!

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.

1 Like
27

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.

1 Like
28

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.

29

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.

30

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…

1 Like
31

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.

:pray:

32

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.

3 Likes
33

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.

34

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.

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?!

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.

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).

Great! Thank you for contributing to the community!

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

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?

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.

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.

35

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.

8 Likes
36

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.

2 Likes
37

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.

1 Like
38

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…

1 Like
39

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”.

40

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.

41

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. :grinning: 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.

42

Ok. It seems that everyone had time to express their opinion and respond to each other.

Thank you for your participation in this discussion.

However I think that this topic has run its course and it takes time monitoring it. Time that could be spent otherwise -if you catch my drift-.

The discussion about improving the Hugo Documentation should continue in the dedicated GitHub repository:

3 Likes
43