[fvsch]

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.