Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

Hugo is awesome, its documentation is not

sagar.se

Post reply on HN
Print view View original

111–120 of 128 posts

Re: Hugo is awesome, its documentation is not

#111

Post by regus »

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…

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.

Re: Hugo is awesome, its documentation is not

#112

Post by SomeCallMeTim »

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…

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.

Re: Hugo is awesome, its documentation is not

#114

Post by [deleted] »

chipotle_coyote wrote: post #104
dahdum wrote: post #82

Earlier quoted context omitted.

As written it seems to me the intent of the article is to publicly shame the open source devs who contribute their time and effort into doing more work for free. It's typical open source toxicity.

This makes me think of the old programmer joke that's something like, "There's no documentation. If it was hard to write, it should be hard to understand." In project like Hugo that has no "user interface" to speak of, tools for which you can't reasonably be expected to just look at the UI screens and figure things out if they're nicely done because there are no UI screens to look at, the documentation is the user in…

[deleted]

Re: Hugo is awesome, its documentation is not

#115

Post by eloff »

sreevisakh wrote: post #80
eloff wrote: post #70

I like Hugo quite a lot, but I don't like Go's standard library templates. I wonder if it is possible to use https://github.com/valyala/quicktemplate with Hugo?

Zola [1] was created exactly for this reason. It even says so in the Readme. The templates are based on Jinja though, not mako. They also claim that their CLI is intuitive and documentation is good. I certainly found it more comprehensible than Hugo's. [1] https://www.getzola.org/

Nice, thanks for the link, it looks interesting. Implemented in Rust.

Re: Hugo is awesome, its documentation is not

#116

Post by stonecharioteer »

I tried Hugo, and Jekyll and my biggest gripe with either is the Markdown format. I prefer RestructuredText and it is truly a superior format. I understand why Markdown is more popular but I can't understand why these static site generators support only Markdown. Sphinx supports both, and I use it everywhere. Paired with Pradyun's Furo theme, it truly is a far better experience.

Re: Hugo is awesome, its documentation is not

#117

Post by mbrodersen »

Writing good documentation is exactly like writing good software: you need to start with a known foundation (the readers prior knowledge/the OS platform) and then build layers of knowledge/software on top of that. One layer at a time. And never have circular dependencies. This is why I recommend only hiring software developers who communicate clearly. Software developers who can’t communicate clearly will write software that is badly structured and hard to maintain. A confused/unclear/unsystematic mind will write confusing/unclear/unsystematic documentation/software.

Re: Hugo is awesome, its documentation is not

#118

Post by subpixel »

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…

https://www.kickstarter.com/projects/1749618880/webhook

RIP - 5 or 6 years ahead of its time.

Re: Hugo is awesome, its documentation is not

#119

Post by zwbetz »

I'm a big hugo fan. I contribute to their forum. I use hugo to build my site. I've used it on freelance projects. I could go on and on about it.

I do hear the concerns here. I agree that the docs are more reference style, and less tutorial style. (Tho, as you gain experience, you prefer the reference style).

After I learned hugo, I wrote the tutorial I wish I would of had. Am shamelessly sharing it here in case it's useful for someone else wanting to deep dive:

https://zwbetz.com/make-a-hugo-blog-from-scratch/

Re: Hugo is awesome, its documentation is not

#120

Post by chipotle_coyote »

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…

Lektor, a Python-based SSG that I've used in the past, actually had a self-contained Mac app for a while that was maybe 75% of the way toward that. (IIRC, the app didn't let you edit templates and most site-level configuration; the idea was more that you got things set up in a more programmer-nerd way first and then used the app for site maintenance/deployment.) Unfortunately, the app broke a few years back and nobody left developing Lektor seems motivated to fix it.

I've seen one other SSG that has an app, Publii, but I've never used it. My impression is that it wasn't as full-featured as Lektor, which could be made to do a lot of neat things. Although if Publii's app still works, that's one big thing Lektor doesn't have, so... :P

Post reply on HN