so this might sound like I didn’t read anything at all but I invested several hours in research, reading the docs and what not but I just can’t figure it out.
Create a site hugo new site mysite
Create layouts/index.html
Now, if we add something to index.html we can see it.
mkdir content/posts
touch content/posts/post1.md
touch content/post/post2.md
Each post is something like
---
Title: first post
---
My first post
Now I want to be able to go to the URI /posts and just see them listed.
I’ve read really really a lot but I just don’t get it.
Can please, please someone point me to the part of the documnetation that doesn’t explain “list templates” and “homepage templates” and all the hundred options but the philosophy behind it? The architecture? The design principles? The inner workflow? The render cycle?
i mean sure, we have the whole Hugo's Lookup Order | Hugo lookup order but how should I know when Hugo uses which of those?
You need a list.html template and possibly an _index.md file in the posts directory. It is in fact all documented, probably in different places though. Read about the list templates in the template section.
I never said it isn’t documented, what I meant is: The documentation lacks giving you the big picture first and then progressively introducing new concepts. Like a user guide. At least that’s my view at the moment.
A good example of what I mean is https://docs.nestjs.com/
The videos go kind of in that direction though - I just never watched them because I dislike watching videos for such things.
but anyway, I think I found one of the issues I had.
I totally agree, just wanted to point you to the place where you might find more info on this. The documentation has no clear focus on a target group, it is oscillating wildly between reference manual, insider description, (often imcomplete) examples and overview. No user guide at all, and not enough distance to the topics to describe them for the uninitiated.