New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add "main sections" site config #3206

Closed
bep opened this Issue Mar 21, 2017 · 13 comments

Comments

Projects
None yet
3 participants
@bep
Copy link
Member

bep commented Mar 21, 2017

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

This comment has been minimized.

Copy link
Member

bep commented Mar 21, 2017

@bep bep changed the title Add calculated Site.MainSection proposal: Add calculated Site.MainSection Mar 21, 2017

@bep bep added the Proposal label Mar 21, 2017

@digitalcraftsman

This comment has been minimized.

Copy link
Member

digitalcraftsman commented Mar 21, 2017

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

This comment has been minimized.

Copy link
Contributor

rdwatters commented Mar 21, 2017

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

This comment has been minimized.

Copy link
Contributor

rdwatters commented Mar 22, 2017

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

@bep

This comment has been minimized.

Copy link
Member

bep commented Mar 22, 2017

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

@bep bep changed the title proposal: Add calculated Site.MainSection proposal: Add "main sections" site param Mar 23, 2017

@bep bep changed the title proposal: Add "main sections" site param Add "main sections" site param Mar 23, 2017

@bep bep added Enhancement and removed Proposal labels Mar 23, 2017

@bep bep changed the title Add "main sections" site param Add "main sections" site config Mar 23, 2017

@bep

This comment has been minimized.

Copy link
Member

bep commented Mar 23, 2017

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

@bep bep added this to the v0.20 milestone Mar 23, 2017

@rdwatters

This comment has been minimized.

Copy link
Contributor

rdwatters commented Mar 23, 2017

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

This comment has been minimized.

Copy link
Member

bep commented Mar 23, 2017

@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

This comment has been minimized.

Copy link
Contributor

rdwatters commented Mar 23, 2017

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

This comment has been minimized.

Copy link
Member

bep commented Mar 23, 2017

  {{ 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

This comment has been minimized.

Copy link
Contributor

rdwatters commented Mar 23, 2017

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

This comment has been minimized.

Copy link
Member

digitalcraftsman commented Mar 23, 2017

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

This comment has been minimized.

Copy link
Member

bep commented Mar 23, 2017

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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment