Types, sections, kinds and layouts


#1

I dug through documentation, themes and various blog posts.
But I have really hard time getting started with hugo.
Maybe you guys help me out a bit.

To understand the whole type/kind/section/layout story I started a small test project:

content/
├── _index.md
├── contact.md
└── post
    ├── slug1
    │   └── index.md
    └── slug2
        └── index.md

Nothing fancy. A home page, a contact page and two blog posts. The posts have tags bug no categories. I have not overridden any types or layouts.
The theme has nothing but files that name their name like default list or page single.

themes/tcurdt/layouts/
├── _default
│   ├── baseof.html
│   ├── list.html
│   └── single.html
├── index.html
├── page
│   ├── list.html
│   └── single.html
├── partials
├── post
│   ├── list.html
│   └── single.html
└── taxonomy
    ├── list.html
    └── single.html

The config is essentially nothing more than

  theme = "tcurdt"
  [taxonomies]
    tag = "tags"

And this is what gets produced - with some annotations:

public/
├── contact
│   └── index.html (page single, clear)
├── index.html (post list, why not page list?)
├── index.xml (want: feed.xml of just posts)
├── post
│   ├── index.html (post list, want: /archive.html)
│   ├── index.xml (want: /feed.xml)
│   ├── slug1
│   │   └── index.html (post single, clear)
│   └── slug2
│       └── index.html (post single, clear)
├── sitemap.xml (ok)
└── tags
    ├── index.html (taxonomy list, clear)
    ├── index.xml (want: removed)
    ├── tag1
    │   ├── index.html (taxonomy list, why not taxonomy single)
    │   └── index.xml (want: removed)
    ├── tag2
    │   ├── index.html (taxonomy list, why not taxonomy single)
    │   └── index.xml (want: removed)
    └── tag3
        ├── index.html (taxonomy list, why not taxonomy single)
        └── index.xml (want: removed)

Why is the home index.html a post list? I could understand page list. But given there is a layout/index.html - why isn’t that being used? According to the docs I thought it should.

I came across multiple threads and questions about the index.xml files. People are asking the same thing. How to turn those off but just keep a single feed?

The disableKinds route is a bit unclear to me. Because when I do:

  disableKinds = ['RSS']

then of course there are no feeds at all.
How I got this kind of working was to use:

  [outputs]
    home         = ["HTML"]
    section      = ["HTML", "RSS"]
    taxonomy     = ["HTML"]
    taxonomyTerm = ["HTML"]

But I don’t see a way to specify per invidual section/type whether I want the RSS or not. Is there a way to define this per type?

Seems like this is the only way to switch to Atom?

https://gist.github.com/lpar/7ded35d8f52fef7490a5be92e6cd6937
https://github.com/lingxz/er

Which seems to disable RSS and bring its own atom template instead. Which also seems to help to define the target URL of the feed. Taling of which…

Can the target URL of “automatic” pages like RSS be changed/aliased somehow?

Or is there another way to change the feed URL for the normal RSS (besides creating another custom output format)?

It’s clear that tags/index.html uses a taxonomy list layout - but why is tags/tag1/index.html a list too? Because it lists pages/posts? Shouldn’t it then be pages list not taxonomy list?
To me tags/index.html and tags/tag1/index.html do not necessarily should have the same layout.

I hope my questions did not turn into a long rant - but I’d appreciate some insights :slight_smile:

cheers,
Torsten

PS: I am running hugo 0.41 darwin/amd64
PPS: Is there a chat somewhere? IRC? Gitter?


#2

Quick amendment:

  1. Somehow it is now a page list :thinking:
    But still I would expect it to use the layout/index.html

cheers,
Torsten


#3

This might help: https://hugo-sandbox.netlify.com/.

See the type/kind/layout annotations at top-left and the site source (linked on each page).


#4

Thanks, @kaushalmodi. Super helpful.
I wish had seen that earlier.

That said it: It adds to the pool of confusion of
Type, Kind, Section, ResourceType, Bundle, Layout.

I used https://github.com/kaushalmodi/hugo-bare-min-theme to gather the following infos:

index.html:
  resourceType=? the debug view doesn't say
  kind=home
  type=page
  layout=
  section=? the debug view doesn't say
  bundle=branch

contact/index.html:
  resourceType=page
  kind=page
  type=page
  layout=
  section=
  bundle=n/a (regular page)

post/index.html
  resourceType=page
  kind=section
  type=post
  layout=
  section=post
  bundle=n/a (regular "list" page)

post/slug1/index.html:
  resourceType=page
  kind=page
  type=page
  layout=
  section=post
  bundle=leaf

tags/index.html:
  resourceType=page
  kind=taxonomyTerm
  type=tags
  layout=
  section=tags
  bundle=n/a (regular "list" page)

tags/tag1/index.html:
  resourceType=page
  kind=taxonomy
  type=tags
  layout=
  section=tags
  bundle=n/a (regular "list" page)

Even with the lookup rules in mind (to me) this does not translate to a clear understanding on how to map this to the layouts in a theme. Which IIUC are along the lines of:

layout/<type>/single.html
layout/<type>/list.html

I wish this was a little more KISS and explicit.

Is there documentation contrasting all these different attributes and making the connection?


#5

You typically don’t need to know the values of all of those values when you are starting out with Hugo. Everything is documented in the Hugo docs, but not in one place.

Let me make an attempt at simplifying these. I will explain the terms in the order of more used (i.e. one that any user will end up having to understand) to less used… from my perspective of course:

  1. Kind: IMO every user must know what “kind” any given page on their site it. Search for “Page Kinds” in doc site.

  2. Section / Type: By default, section (and type) is the first level of directory in your content directory. If you have content/posts/ all content files in there, even in nested directories will have the section and type set to “posts”.

    • For other pages where an associated content file doesn’t normally exist, like tags, categories, etc, the section and type is, crudely speaking, that first level of directory in the rendered output.
    • Search for “Sections” in documentation.
  3. Bundle type: You need to know the bundle type if you have index.md and _index.md content files. If not, ignore this.

    • See the Page Bundles documentation for more.
  4. Layout: This parameter is also left untouched most of the times. It’s present for user customization on which layout file to apply to a given content file. Again, it’s modified using a front-matter, layout. It’s implied value is “single” for page kind pages, and “list” for all other page kinds. The homepage (while would fit under “list” layout too) typically a special layout file called “index.html”.

    • The layout front-matter is documented. But may be the “implied value” needs to be better documented.
  5. Type: If left untouched, this is the same as section. But this, unlike section, can be modified using the type front-matter.

    • For homepage kind, type defaults to “page”… My understanding is that that’s for internal use in Hugo, or for legacy reasons. For homepage, section is “”. So probably Hugo sets it to a default non-empty-string value… “page”? … That said, you don’t have to worry about type as long as you are not customizing it.
    • The type front-matter is documented.
  6. ResourceType: I haven’t yet needed to care about this. As you see it defaults to “page”. Also you cannot customize this.

    • I have to confirm but I believe this is set to a non-“page” value only for non-page resources in Page Bundles. Look up the Page Bundles and Page Resources documentation. Personally I have not yet needed to care about this one. And this definitely has nothing to do with page layout lookups.

The layout lookup order follows this:

layouts/<TYPE>/<LAYOUT>.html

See the many examples in Layout Lookup in docs. That will help blend the above explanation with those examples.