fvsch

This matches my impression of Gatsby after a day with it. I bailed a bit more quickly than with Hugo, so I refrained from adding a Gatsby section to my already too long article. Also my main takeaway was “Gatsby is an overengineered mess from (and favored by) people who are already all-in on React and GraphQL and don’t realize the learning curve they’re asking others to climb to build simple sites”. Too categorical for something I’ve only spent a short day with, so I decided not to include it.

While I do know React well enough, when trying to work with local content I had to follow a tutorial that asked me:

1. To install 2 plugins 2. To copy-paste 3 different chunks of boilerplate code (configuration, the code that maps filesystem data into some kind of representation — maybe using GraphQL already, I’m not sure — and lastly the GraphQL queries to retrieve that data). 3. To personalize this boilerplate code, which requires me to learn GraphQL.

Other tools can do similar work without plugins, without having to learn a second language (GraphQL) separate from the core language that the tool is using (JavaScript), and without having to write code to feed content into a in-program representation yourself.

It could be that all this overhead is worthwhile because it enables you to do complex things. But from what I’ve read I wasn’t even sure that Gatsby could achieve my use case without me duplicating my information architecture as “feed content to the in-program representation” code, and I didn’t want to risk spending a second day only to find out that it couldn’t. (Your comments about tree navigation, as well as some of the GitHub issues I’ve read, suggest I was right to bail out.)

My actual takeaway is that Gatsby might be a good fit if you already know React and GraphQL (or already wanted to spend time learning those), and are working with remote content from a headless CMS and some other sources. But for local content only, unless you already know Gatsby or want to use that project to learn it, it’s needlessly complex and overkill.

My point in that article was indeed about complexity and the difficulty of learning many concepts. How do you figure which concepts are actually "the same"? If they are indeed the same, why ask users to pay the cognitive cost of learning five concepts then figure out that they’re synonyms? But are they really the same, though? I gather that they must do a few things differently. In my experience when I renamed a `index.md` to `_index.md`, I lost access to one feature and got access to a new one (my issue was that I actually needed both!).

The section I wrote about Hugo, and indeed my whole article, is not purely about technical capabilities. It’s about user capabilities when using specific software, so there’s some focus on what the software can do, but also on the user’s perception of what the software can do and on the learning curve.

In my day-and-a-half with Hugo, I’ve read most of the docs twice, and have read some old issues and release notes. It looks like some of the complexity in Hugo’s design comes from adding features and redesigning some features over time. This process tends to accumulate cruft, and calls for compromise between conceptual clarity and backwards compatibility.

At one point I’ve read release note (for 0.20 I think) that said something like “from now on, everything is a Page”, but was surprised that different kinds of pages had access to different kind of data, somewhat arbitrarily. By contrast, if you start with a concept like “everything is a page and has a predictable feature set”, it’s easier to have this simpler design correctly implemented and correctly reflected in documentation.

If you’re not against PHP and hosting PHP code, as mentioned in the OP my go-to tool would be Kirby. The mix of static content and a powerful content API is the sweet spot for me, when I don’t absolutely need static HTML. It does require a paid licence though (note: I’m not affiliated with Kirby or its developers).