So after reviewing this for more hours, here are updates:
- like many other posters mention, hugo has pretty bad onboarding (probably a high churn/bounce rate)
- the documentation- while extensive… is “off” (this from someone as professional developer, who knows go and has done html/css for 20 years)
- not sure if this is because of a language barrier?
- it’s very impractical, it reads more like a dictionary
- although it has a lot of specificity in it’s organization, it’s impractical and not pragmatic
- example, when looking at date formats… there is a lot of stuff written… but it’s not how to change a format or where, or what it would look like.
- you’re basically constantly googling for plausible examples to try and hope they work for the correct version
We were able to take existing examples and modify them to start to import existing sites, but it was very trial-and-error. So many people have had this problem that there are tons of hugo posts explaining how to do certain things, but there is no carnoical example and they all use different versions.
Somewhat complicating things is that hugo itself doesn’t generate a complete skeleton. So the idea of a partial template (what other generators usually call compoents) is cool and seems well executed. But the hugo new site doesn’t create ‘partials’ by default!
So you’re constantly guessing and crossing your fingers. It’s super inefficient.
That said, this is the best resource I’ve seen and it should be included in the defacto hugo docs. It’s up-to-date with current version of hugo. It example of how to use hugo in a handful of commands and is both very simple and illustrative of important hugo concepts. (I do note that while it references the very thorough hugo docs, it doesn’t characterize their opaqueness and lack of practicality).
Put another way… if standard hugo getting started is the 1min guide, this resource is the 5min guide. I’m linking it again because it didn’t show up in google and I only found it because the other DM-ed it to me.
Actually wondering if it would make sense to fork hugo into another project that just wraps it with better example, a full project skeleton when doing ‘hugo new site’ and english-native documentation. (the first two are pretty easy, the last is big project but also why the developers probably don’t want to work on this)