[throwaway284534]

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 scouring through the Go docs and Hugo’s own forums for a complete and pragmatic solution.

I had a heck of a time with Hugo’s concept of “Scratch” while generating a breadcrumb navigation. Combined with a JSON schema, Google will include these crumb segments in search results. But much like Handlebars, Go template expressions aren’t REPL friendly, and a the learning experience involves a lot of refreshing and debug output just to get a clue as to how things work.

Personally, this has bitten me with every “stringly” typed template language. IDE’s have little information to work with, and much like playing a game of Wordle, you’re left to fill in the blanks — one line at a time.

[SomeCallMeTim]

Very much the same experience.

The whole "They Are Just Go Templates" is a pretty pathetic cop out. Sorry, but it's true. If I'm trying to use Hugo, I don't want to be digging in Go docs at the same time, and as you point out, you can't know things like scopes and what Go variables might actually be available.

And yes, most of the actual syntax is simply not documented.

I subsequently gave up on Hugo entirely and ported my Hugo sites to Next.js, which is in fact documented--and can work well with TypeScript, so complex pages are fully strongly typed, which makes work in an IDE a breeze.

[regus]

I agree with you completely about the templates. When I first used Hugo I was not well versed in Go, nor did I have any idea how it's templating system worked.

Reading the docs lead me to believe that the templates were invented by Hugo. It would of been helpful to make the distinction because I could have looked up how the templates work. I'm not sure if it would have helped though because Go's templates are incredibly confusing and frustrating to use.

[bborud]

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.

[rr808]

I've had the same issue with Helm Templates - "they're just Go templates".