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

Show comment
Hide comment
@bep
Member

bep commented Mar 21, 2017

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

@bep bep added the Proposal label Mar 21, 2017

@digitalcraftsman

This comment has been minimized.

Show comment
Hide comment
@digitalcraftsman

digitalcraftsman Mar 21, 2017

Member

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 }}
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.

Show comment
Hide comment
@rdwatters

rdwatters Mar 21, 2017

Contributor

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.

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.

Show comment
Hide comment
@rdwatters

rdwatters Mar 22, 2017

Contributor

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

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.

Show comment
Hide comment
@bep

bep Mar 22, 2017

Member

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

Member

bep commented Mar 22, 2017

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

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

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

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

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

@bep

This comment has been minimized.

Show comment
Hide comment
@bep

bep Mar 23, 2017

Member

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

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.

Show comment
Hide comment
@rdwatters

rdwatters Mar 23, 2017

Contributor

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.

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.

Show comment
Hide comment
@bep

bep Mar 23, 2017

Member

@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.
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.

Show comment
Hide comment
@rdwatters

rdwatters Mar 23, 2017

Contributor

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.

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.

Show comment
Hide comment
@bep

bep Mar 23, 2017

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

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.

Show comment
Hide comment
@rdwatters

rdwatters Mar 23, 2017

Contributor

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.

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.

Show comment
Hide comment
@digitalcraftsman

digitalcraftsman Mar 23, 2017

Member

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.

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.

Show comment
Hide comment
@bep

bep Mar 23, 2017

Member

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

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