Add "main sections" site config

[bep]

I scribble this down, it may be a crazy idea.

But thought of this when reading the "default theme" thread.

One of the main issues we have with themes is the portability, they make some assumptions that aren't common to all themes.

One of them is this construct in the home page template:

  {{ range where .Site.Pages "Section" "Post" }}

And similar. Which is bad if the main section is named something totally different.

One other option is then:

  {{ range where .Site.Pages "Section" .Site.Params.mainSection }}

But, what if we nominate the section with most pages as somewhat special:

  {{ range where .Site.Pages "Section" .Site.MainSection }}

Or even better:

  {{ range  .Site.MainSection.Pages }}

[bep]

/cc @rdwatters

[digitalcraftsman]

As a workaround I would propose that users should define a list of sections that should be used to filter the content files. Only content that is part of one of these sections will be displayed:

  {{ range where .Site.Pages "Section" "in" .Site.Params.displayedSections }}

[rdwatters]

But, what if we nominate the section with most pages as somewhat special

With the ability to override in site config, I assume? Then YES. This will at least cover the discrepancies for the most common use case with existing themes (i.e., blogs who want to use "blog," "posts," and even "articles"). Are you thinking you would extend/abstract this even more for larger sites; e.g., primary section, secondary section, etc., @bep?

As an aside, I think there is value in being a little more prescriptive in our "submit a theme" docs for known knows: e.g., relURL.

[rdwatters]

@bep How are you feeling about this? Shall we add a user feedback tag?

[bep]

No, let us wait. There is too much going on at the moment.

[bep]

OK, this will take some time to get its way into the themes (we can do some bulk PRs to speed it up), so we should get it out in the wild sooner than later.

I agree with @digitalcraftsman -- we do it simply with no magic.

• Add a site config var, a string slice of "blessed" sections, the name is the hardest here: mainSections? (and put it in .Site.MainSections -- a little more formal than a site param)
• If not set by the user, we set it to the default value ["post"] (see below)

▶ find . -name "index.html" | xargs grep "\"post\"" | wc -l
      56

~/hugo/hugoThemes  master ✔                                                                                                    82d
▶ find . -name "index.html" | xargs grep "\"blog\"" | wc -l
       5

Addendum: We should probably use the "biggest section" as a default if not too much work finding it.

/cc @rdwatters @digitalcraftsman

[rdwatters]

We should probably use the "biggest section" as a default if not too much work finding it.

Agreed. Are you thinking total number of files for a top-level section? Just considering the work you're doing on nested sections and which of the following would qualify:

1. content/posts/ = 20 .md + 1 dir
2. content/posts/travel = 50 .md

biggest section == 2 ?

Or just that...

1. content/posts/ = 70 .md and, therefore, biggest section ==1

the name is the hardest here

I think mainSections works really well. For the sake of conversation, do either of you think new or existing themes would have the highest number of markdown files at the content root?

@digitalcraftsman, with respect to your example usage but tweaked slightly:

{{ range where .Site.Pages "Section" "in" .Site.MainSections }}

How would a theme developer define, for example, a primary vs secondary section; e.g.blog vs tutorials?

If this is up and running, I can help with PRs for themes. Might be a good opportunity for me to fix some of the other common issues.

[bep]

@rdwatters you raise a lot of questions not relevant to the current Hugo situation (there is only one level and we are not talking about secondary sections here).

So the spec is:

• Add Site.MainSections slice.
• If set in site config, use those values.
• Else pick the first section with most pages.

[rdwatters]

you raise a lot of questions not relevant to the current Hugo situation

From my previous comment but with emphasis added:

I think mainSections works really well. For the sake of conversation, do either of you think new or existing themes would have the highest number of markdown files at the content root?

---

there is only one level and we are not talking about secondary sections here

Then why mainSections rather than mainSection?

"Secondary" and not "nested," as in, for example, "primary" having 60 files and "secondary" having 20 files, per my question above regarding how you want to calculate the biggest section and my example of blog vs tutorials. Would you please provide an example of usage similar to @digitalcraftsman to help me better understand?

Thank you.

[bep]

  {{ range where .Site.Pages "Section" "in" .Site.MainSections }}

So there can be many main sections (up to the user), and there will be an implicit order (array index), but the common usage doesn't care about that order. We haven't defined a use case where order is important, so we don't make it more complex than it is.

And if the user have not specified what he wants, we make a guess by counting. And that is currently very simple. No hard rules. If two sections have the same amount of pages, one of them wins (ordered by section title, maybe, it doesn't matter as long as it is stable).

So if primary have 60 files and secondary have 20 files, which section do we pick? The primary.

[rdwatters]

and there will be an implicit order (array index), but the common usage doesn't care about that order.
If two sections have the same amount of pages, one of them wins (ordered by section title, maybe, it doesn't matter as long as it is stable).

Got it. Thanks for the example @bep. I'm grokking it now and trust that you have all this covered w/r/t your future plans for nested sections. I only ask to learn 😄

And 👍 on mainSections for sure.

[digitalcraftsman]

The addition of .Site.MainSections is a good idea to make the improve experience across themes. I've got similar feature requests in the past. Having a standardized solution is the best way to reply.

[bep]

... but thinking about it I think we should make it .Site.Params.mainSections; that way we keep it backwards compatible with old Hugo versions.

[github-actions]

This issue has been automatically locked since there has not been any recent activity after it was closed. Please open a new issue for related bugs.