Feedback wanted: Nested sections: Content structure

I simply don’t like the leading underscore idea. It’s not intuitive and is too limiting.

Alternative: Support Standalone Metadata Files In Content Dir

One of the ideas from @spf13’s “Hugo Next” brain dump was supporting a metadata.toml file inside of a directory so that you could separate the page metadata from the content file(s). We could extend that idea to sections, whereby, if we find a metadata.toml file with type = section (or something) defined, we treat that node in the content tree as a subsection. It also allows us to add metadata about the subsection itself (if that would be helpful).

▶ tree content
content
└── blog
    ├── subsection1
    │   └── metadata.toml
    │   └── first-subpost.md
    ├── first-post.md
    ├── second-post.md
    └── third
        └── index.md
1 Like
  • How is it limiting?
  • How is it more intuitive to put a metadata.toml file with some configuration variables in it? Both need documentation, the “_” is, I would say, easier to document than the TOML file. Not?

@moorereason note that I’m not saying that what you say does not makes sense – but it would be nice with arguments beyond “I don’t like it”.

If we go the metadata way, I would say that a more natural fit would be to put it in “_index.md”.

But looking ahead, I see 3 different types of directories:

  1. Sections (including the nested)
  2. Just regular directories (as a logical way of managing 1000s files)
  3. Bundles

The first 2 are kind of booleans – either or, and I would not need more than a flag (say, a “_” prefix) to determine.

For 3) I would probably also need some additional metadata, but not necessarily in its own file (aka. metadata.toml); if a bundle always contain 1 content file, why not configure the bundle in that?

My main point is, I don’t know enough about bundles to commit to any design.

  • Adding a new config file now and see that it’s not needed 3 versions from now, would be bad.
  • Adding a naming convention now and see that it is superfluous 3 versions from now, would be liveable.

I agree with this. _Index.md is more convenient for a folder, because it allows to have content and metadata.

it would be nice with arguments beyond “I don’t like it”.

Sorry, I was tired and in a hurry, so I skipped the “why” part.

How is it limiting? not intuitive?

I agree that the underscore prefix is simple, but…

We essentially ban the use of underscore-prefixed directory names. How do we add metadata for the subsection? Do we deviate from how we define metadata for other content (which is also an argument against metadata.toml)?

a more natural fit would be to put it in “_index.md”.

Agreed! I’m in favor of this approach. :+1:

But looking ahead, I see 3 different types of directories: …

I agree with everything you said in this section.

As a general principle, I think we should avoid reserving any additional path names if we can, esp. naming patterns like “any directory with a leading underscore.” We need really good arguments for reserving more names/patterns, and I don’t think this case is a good one. And as you pointed out, we don’t have a good argument for reserving metadata.toml at this point either.

1 Like

OK, this actually makes the implementation simpler as well.

So:

Any _index.md below content marks that directory as a section … if it is not a taxonomy …

Note about the above:

  • The first directory will still be a section even if it has no _index.md (i.e. blog, posts etc, like today)
  • We don’t add any metadata, but this opens up for other interpretations later, i.e. bundles.
2 Likes

This makes solid sense to me and doesn’t add another gotcha with an underscore.

@bep this is about content structure, but that also has to do with type inheritance w/r/t sections. In your example above, does third/index.md assume a type of third or blog? Does subsection assume a type of _subsection or blog?

If it’s possible, I wouldn’t recommend adding complexity to the lookup order. So, for example, if first-subpost.md assumes a type of subsection (unless otherwise specified in the front matter), the lookup order is still…

  1. /layouts/<TYPE>/<LAYOUT>.html
  2. /layouts/subsection/<LAYOUT>.html
  3. /layouts/<TYPE>/single.html
  4. /layouts/subsection/single.html
  5. /layouts/blog/<LAYOUT>.html
  6. /layouts/blog/single.html
  7. /layouts/_default/single.html

…repeat for themes…

Or is…

…replacing #2 and #4 above but still piping in the parent layouts in the order?

What? As I said, “third” is just a “regular folder”, i.e. not a section. But we have had people who have used this as a “poor man’s bundle”, hence the index.md – there were some shouting about me breaking that pattern a month ago…

And as I said, this is not a discussion about template lookup orders. We may improve on that, but there is a thing called “doing one thing at a time”.

Yes, I remember this. “Type inheritance” sounds too programmerish in this case. What I meant was Hugo assuming that a .md file’s type is equal to .Section unless otherwise specified in the front matter and whether this assumption would carry over for the nested section as well. But the idea of _index.md == section makes sense and kind of answers this already.

Cool. But I’m not talking about improvements as much as whether this would continue to observe the existing lookup order. And, you’re right, we can skip that part of this thread entirely :smile:

A .Section is a section, which is well defined. There is no front matter magic involved. Does the documentation say anything else?

I’m thinking mostly about here:

Which is more or less the same in the new docs:

https://hugodocs.info/content-management/types/#assigning-a-content-type

It seems a common hack has been to declare a type in a subsection’s content file front matter for filtering/sorting since a subdir under content now assumes the parent’s section (and by default, type). I think this was my line of reasoning w/r/t my earlier question about Data.Pages.

I’m not sure I follow;

  • We have .Section, which is the first folder below /content
  • Then we have .Type, which if not set in front matter, will get its value from `.Section``

I have not thought this through in its entirety, but it may be the most sane thing to keep .Section as is today (i.e. “blog”, the first root), and add some other getter to get the full slice.

It might be better if I put together a sample tree and post it in a few hours. Otherwise writing all this out will be a novel. I’ll post or DM in a few hours after work, @bep. Thanks.

have there been any improvement on the matter?

it would be a hell of a feature if we could have support for sub sections.

thank you @bep.
it seems then, that I’ve not been able to get it to work.

I have this structure:

content
├── folder
    └── subfolder
        └── _index.md

but I can’t make it work with the layout at

layouts/folder/subfolder/list.html

do you confirm it should work? if that’s the case I’ll continue testing and look into a possible my mistake.

1 Like

Nested sections cannot have their own templates.

I have workaround for this.

In _index.md I still keep both type and layout, so it is there when Hugo will support it:

type: "school"
layout: “state”

Then in /layouts/school/list.html I added:

{{ $layout := add .Params.layout “.html”}}
{{ partial $layout . }}

so in this case I added state.html to my partial layouts.

I will close this very old thread that discussed the development of this feature.

1 Like