Documentation is sometimes confusing/contradictory

[jrpear]

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.

[jmooring]

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.

[coliff]

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.

[jmooring]

Pasting from Google Doc provided by OP:

Content Organization

• Item 1: Single Pages in Sections’s example of a single post within posts shows that path includes slug, while Paths Explained says “path -> does not include the slug”

Page Bundles

• 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.”

• 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

• 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.

Page Resources

• Item 5: Unclear sentence “Resources are only attached to the lowest page they are bundled with, and simple which names does not contain index.md are not attached any resource”

Template Lookup Order

• 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 Fix typo in output-formats.md #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 Fix typo in output-formats.md #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

Output Formats

• Item 12: Media Formats “Redefine HTML to update its media type” example is only in toml

Hugo Pipes

• Item 13: Files in the /assets directory are accessed and manipulated using the resources namespace; meanwhile there is a resources folder that is not accessed this way.

[jmooring]

Status of items from previous comment...

Item 2

This will be addressed with #2307

Item 2

This will be addressed with #2307

Item 3

This will be addressed with #2307

Item 4

This will be addressed with #2307

Item 5

This will be addressed with #2307

Item 12

This was addressed a while ago. Example now uses code-toggle shortcode to show configuration example in TOML, YAML, and JSON.

Item 13

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.