Hugo is awesome, its documentation is not • Hacker News Board

Re: Hugo is awesome, its documentation is not

#121

Post by esperent » Thu, Mar 03, 2022, 7:05 AM UTC

CA0DA wrote: post #3

This gives a few good examples of how the Hugo documentation could improve (the click-bait word "Sucks" in the title is a bit exaggerated, in my opinion). I would challenge the author to, in the spirit of open source, go ahead and make some of the suggested changes and submit the changes in a Pull Request!

I have actually opened a pull requests [1] on the Hugo docs, adding one small sentence to clarify something that I was stuck on for several hours.

It was ignored for over a year, with the only comment being from me, then automatically marked stale and closed.

Needless to say I didn't open any additional PRs.

Also, this reflects my impression of the Hugo community in general - their discourse forum is pretty dismissive to questions (lots of "have you read the docs?" type responses when yes, I did read the damn docs, found them utterly confusing and that's why I spent 20 minutes writing up a detailed forum post to ask for advice).

[1] https://github.com/gohugoio/hugo/pull/6398

Re: Hugo is awesome, its documentation is not

#122

Post by mateomorris » Thu, Mar 03, 2022, 10:06 AM UTC

lolinder wrote: post #109

chipotle_coyote wrote: post #101

Earlier quoted context omitted.

Almost off-topic, but I continue to be mildly surprised that there's so few "modern" blogging platform/site generators that use Movable Type's model: a full user-friendly publishing/admin back end, backed by a database rather than flat files, but still basically generating static files for output. The SSGs that Jekyll arguably led the rise of have still largely stayed in the realm of developer tooling -- edit a direc…

One of the big reasons I lean toward static sites for my stuff is that you can host them out of an S3 bucket or similar with no dynamic endpoints whatsoever. This is a huge win for security for projects that I don't have time to keep constantly updating. A web-based admin backend largely eliminates that value unless it's run off a separate port that I can firewall, and even then I have to be sure I firewalled it corr…

I think you’re looking for Primo: https://primo.so

Re: Hugo is awesome, its documentation is not

#123

Post by CA0DA » Thu, Mar 03, 2022, 1:58 PM UTC

esperent wrote: post #121

CA0DA wrote: post #3

This gives a few good examples of how the Hugo documentation could improve (the click-bait word "Sucks" in the title is a bit exaggerated, in my opinion). I would challenge the author to, in the spirit of open source, go ahead and make some of the suggested changes and submit the changes in a Pull Request!

I have actually opened a pull requests [1] on the Hugo docs, adding one small sentence to clarify something that I was stuck on for several hours. It was ignored for over a year, with the only comment being from me, then automatically marked stale and closed. Needless to say I didn't open any additional PRs. Also, this reflects my impression of the Hugo community in general - their discourse forum is pretty dismissiv…

Huh, yeah that is disappointing.

I think the stale bot in Hugo repo is overly aggressive. I have had to "fight" the stalebot in the past by posting update messages.

Re: Hugo is awesome, its documentation is not

#124

Post by bborud » Thu, Mar 03, 2022, 5:57 PM UTC

throwaway284534 wrote: post #55

My most frustrating experience with Hugo is their template language and lack of clear explanations, often waiving away any complexities as, “They’re just Go templates.” Fair enough, but the docs make no attempt to explain how scoping works, how variables can be applied to partials, or even how to construct a simple for-loop. There’s an answer for each of these problems but implementing a full solution requires scouri…

If something is a pain in the ass to document, it is probably not very clear. Hugo has a bit too much implicit magic that feels unnecessary. It wouldn't have killed us users if things were a bit more explicit.

Every time I restructure how I do my personal website I get a strong urge to sit down and write a more disciplined static website generator. (Don't worry. I won't. I don't have that kind of spare time on my hands). Obviously one that has fewer degrees of freedom so as to make theming meaningfully possible. Because Hugo themes aren't really themes. They are more like applications where your website probably isn't going to work without a lot of hacking.

Re: Hugo is awesome, its documentation is not

#125

Post by ListeningPie » Thu, Mar 03, 2022, 7:17 PM UTC

I gave up on the documentation and have been reading "Build Websites with Hugo" by Brain P Hogan. It's a step by step guide to a build website, and I find Hugo more approachable and understandable than React Static and Gatsby.

Re: Hugo is awesome, its documentation is not

#126

Post by bphogan » Fri, Mar 04, 2022, 9:09 PM UTC

alleycat5000 wrote: post #46

I've also found Hugo's docs hard to use, but had a great experience learning it from https://pragprog.com/titles/bhhugo/build-websites-with-hugo/

Hey, author here. Thanks so much for the kind words! I love Hugo, and I wanted to give people a real-world tour of how to build something concrete with it.

Re: Hugo is awesome, its documentation is not

#127

Post by dmitriid » Sat, Mar 05, 2022, 4:00 PM UTC

PaulHoule wrote: post #72

rr808 wrote: post #63

Earlier quoted context omitted.

Right its easier to switch entirely to something else. If you use Micronaut, Microprofile, Vert.x etc your life is much easier.

It's been years since I've using Spring. Everybody who pays me to work in Java has used Guava for a while. Most of what I do on my own account is in Python or C (yuck!) or AVR8 assembler. The one Java project I am working on for myself uses balls-to-the-walls metaprogramming and code generation and is designed to enable even more metaprogramming and code generation and doesn't need dependency injection. I spent a lot…

> It's very nice that Spring provides a "general configuration file" that lets you patch together a few objects without having to compile anything.

The problem is: how exact do you configure those things? How do I find which nested incantation, and in what format, is applicable to something?

Re: Hugo is awesome, its documentation is not

#128

Post by apprewired » Mon, Mar 07, 2022, 2:58 PM UTC

earthboundkid wrote: post #88

rsolva wrote: post #29

Earlier quoted context omitted.

I have brought up this exact point on the Hugo forum before [0]. Hugo would become much more accessible if the documentation would be split into the four categories mentioned in the link you provide. This way of thinking about documentation should be the default, and any open source project (or closed for that matter) would benefit hugely by adhering to these simple principles! 0: Discussion: https://discourse.gohugo…

I tried to start a discussion about documentation as reference vs. tutorials on the forums too: https://discourse.gohugo.io/t/discussion-of-hugo-theme-from-... I think the problem is just that no one wants to bell the cat. :-(

I really like the saying 'bell the cat' as well. Anyway, came here to say that I started to do this (create the missing documentation that would've been helpful for me) - it is by no means ready ( on mobile this site looks almost unreadable ) but it is a start: www.hugotutorial.com - if you have any feedback, I would love it!