Thinking about sections logically - quick confirmation question

support
1

Hi,

Loving Hugo so far, but wanted to confirm that I understand site organisation properly.

(1) Sections, is a concept only within Hugo. There is no ‘actual’ sections element.

(2) Assuming the following model, and assuming I am trying to add a section called ‘documentation’, is it appropriate to use a ‘section’ in the following way? Please note I expect www.example.com/documentation/ as the output.
(a) layouts/documentation/list.html for the main list page.
(b) content/documentation/_index.md for the frontmatter + any content for the main documentation page [i.e. www.example.com/documentation/index.html].
© archetypes/documentation.md will drive the archetype if required. Can i ask why is this not archetypes/documentation/list.md or whatever? Or is it and I am confused?
(d) data and partials is confusing. Why is partials inside layouts as opposed to on its own like data. I mean I get why it is there, but when i think about it, I want sections (as a mental concept) to own the mappings (driven by config.toml in my head)

So for each ‘section’, i want to have a folder in archetypes, content, layouts, and data and partials independently. This means, not so much that everything is a page, but rather everything is a ‘section’, and the home stuff can happily hang out in ‘section’ _default. Or have I just misunderstood this and what I am thinking of as a ‘section’ is how you guys think of as a ‘page’?

Please note, the above is not a criticism of the design decisions taken in building Hugo. I am trying to understand it better to work out how to use for my specific use case.

.
├── archetypes
├── config.toml
├── content
├── data
├── layouts
├── static
└── themes

Thanks so much.
Tat

2

Sorta. You don’t need folders in archetypes—just individual archetypes that represent each section.

Partials make the most sense in their current location since you should conceive of them as “partial templates.”

It sounds like you are getting the right idea on how to organize your projects, but don’t feel that things need to be that rigid. Hugo has been designed to leverage a lot of smart “sane defaults” to keep your templating dry. One thing you should definitely familiarize yourself with is Hugo’s lookup order. (Btw, this applies to more than just templates.) If you are a new user, the following is from the docs concept site and I would certainly appreciate any feedback:

https://hugodocs.info/templates/lookup-order

3

@rdwatters - massively appreciate the super quick response. Follow up q if ok? I think I understand how you are thinking about archetypes.

(a) So technically, frontmatter in a section’s _index.md is the single archetype for that section. A archetypes/<section-name>.md is the frontmatter for a section’s list archetype?
(b) trying to better understand the logic, section ‘root’ can be described as layouts/index.html or layouts/_default/list.html? Taking the example a little bit further (for illustrative purposes), would a custom 404 be able to be described as layouts/_default/404.html in addition to the current layouts/404.html?

4

I think the way to think of it is that the frontmatter for any piece of content is really setting metadata for that piece of content. A section’s _index.md doesn’t need any specific frontmatter from an archetype, though if you create it using hugo new <SECTION>/_index.md it will of course have it.

Depending on how you are rendering that section, you will have some variables that you definitely want, like maybe a title or something.

There is a specific lookup order for the homepage which starts with /layouts/index.html. Note that there is also a different lookup order for sections.

404’s are kinda weird. Whereas your site can only have a single homepage, it is also common for webservers to serve a specific template when that error code is encountered; hence 404.html is an not like the other pieces of content you will build with Hugo.

I don’t fully understand your “b” question, so maybe just keep in mind that there are different lookup orders for different template, and focus on one lookup order at a time (in this case, sections).

2 Likes
5

thank you sir. most appreciated.