Open jrpear opened 4 years ago
Constructive feedback is welcome and valuable. Whether or not it will be acted upon depends on the context, content, and resources available to make and review the changes. We are all volunteers.
This is good feedback @jpear1 - thanks for taking the time to write up that Doc! I agree that there are parts which could be clearer. I'll re-open this issue.
Pasting from Google Doc provided by OP:
[x] Item 2: Under the Allowed Resources table entry, what are page vs non-page resources? This table entry says that an image is a non-page resource, but the page resources page says that page resources are “images, other pages, documents etc.”
[x] Item 3: Under Leaf Bundles Examples, the formatting makes it look like image1 and image2 are also leaf bundles, but they’re actually resources of my-post
[x] Item 4: Headless Bundle introduces some strange new syntax:
{{ $headless := .Site.GetPage "/some-headless-bundle" }}
As a new user I have no idea what language this is or where to go to get more info on it. Is it some sort of templating language? I think just a little intro sentence here with a link to the relevant docs would be helpful.
[ ] Item 6: First header is titled “Hugo Layouts Lookup Rules”. “Layouts” and “templates” seem to be used interchangeably. What’s the difference, if any?
[ ] Item 7: Under the Hugo Layouts Lookup Rules, it would be nice to have a link to read more about “Kinds”. I remember reading about them earlier, but I’ve mostly forgotten, and none of the sections have the word “Kind” in the title.
[ ] Item 8: Under Hugo Layouts Lookup Rules, it’s not clear which of the rules are used to prioritize the search folder and which are used to prioritize the search file. My current understanding from looking at examples is: Layout Type, and Section determine folder, and Kind, Output Format, and Language determine file.
[ ] Item 9: Related to above: A little more detail in the lookup rules would be nice. Right now there’s a couple things in the examples that don’t seem to be consistent with the rules:
[ ] Item 9a: Table 1, Example #2: layouts/posts/baseof.html.html comes before layouts/posts/single-baseof.html, but “Kind” comes before “Output Format” in lookup rules.
[ ] Item 9b: Table 1, Example #2: layouts/posts/baseof.html comes before layouts/_default/single-baseof.html.html, but “Kind” comes before “Section/Type” in lookup rules.
[ ] Item 10: Priority rules and examples don’t mention conflict resolution. What if there’s a layouts/posts/single-foo.html and a layouts/posts/single-bar.html where foo and bar don’t influence priority?
[ ] Item 11: Priority rules and examples don’t mention theme priority. What if there’s a layouts/posts/baseof.html and a themes/cur-theme/layouts/posts/baseof.html
Status of items from previous comment...
This will be addressed with https://github.com/gohugoio/hugoDocs/issues/2307
This will be addressed with https://github.com/gohugoio/hugoDocs/issues/2307
This will be addressed with https://github.com/gohugoio/hugoDocs/issues/2307
This will be addressed with https://github.com/gohugoio/hugoDocs/issues/2307
This will be addressed with https://github.com/gohugoio/hugoDocs/issues/2307
This was addressed a while ago. Example now uses code-toggle
shortcode to show configuration example in TOML, YAML, and JSON.
This was addressed a while ago while updating https://gohugo.io/getting-started/directory-structure/. A detailed explanation of the resources
directory was not present in earlier revisions.
I'm going through the documentation and coming a across a lot of confusing things.
First, is it supposed to be approachable for new users? I went through "Getting started", but still didn't know how to format my site, so I started on the next section, Content Management. If there's another place I should look instead, that would be great to know (and maybe link to from the quickstart guide).
If it is supposed to be, I've started putting together a document of things I don't find very clear: doc.
Judging by what I've written so far, is this feedback valuable and would be acted upon by someone? Is there anything I can do better or focus on more? I'd just like to know before I go and write it all up.