| I recently started using Hugo for a few websites. I endorse this. To give a concrete example, I spent quite a while just figuring out what it means to put a piece of content into a directory under hugo, and I still don't have a full grasp on it, honestly. What does it mean to put something under "content/posts/2011" versus dumping it into content/posts? How exactly do categories and tags get populated? (What is the difference between them?) Something as basic as that has taken me quite a while to get through. (Please note I am not asking for answers to those questions here. In fact dumping the answers here in a nice, clean, easy-to-understand format that walks you through from start to finish would be in some sense actively counterproductive. Go dump them in the Hugo docs!) I can not point you at a specific page that describes the answer to this question. I can not point you at a specific page that describes how we get from content to the various collections of content. This documentation exists, but it's buried in a generic listing that has tons of other stuff, and IIRC still doesn't describe edge cases; I was experimenting with things just to see what they did, because I don't think the docs even acknowledged the edge case. Also, there's a lot of stuff made available in the templates but there's nothing like type-level documentation that says what is of what type and what that type can do; collections of pages will be described almost literally as that, but with no link to exactly what a Page object is. Again, it's probably all there somewhere but it's very hard to use. I mean, technically it's all there, but I certainly had to go on an adventure to get it all. The tutorial also suffers from being too simplified. Tutorials always have this temptation to show off all the magic being used in its simplest possible default configuration, which is fine, but then if you want something other that the simplest possible default configuration you're left with not much to go on. It could be worse, but it certainly has some organizational problems. No matter what problem I come the documentation with, be it looking up what an API does, trying to understand a subsystem, understanding the whole thing holistically, figuring out why I want a certain feature (I almost manually recreated the entire concept of a manual taxonomy before figuring out what it actually meant), the docs just never quite manage to answer my question. |