Proposal: Deprecate sections

[bemyak]

Yeah, I know, it sounds like a big change, but please hear me out

Prior discussions:

• Section vs Page

Issues with the current approach

1. Zola’s code has huge duplications. Having pages and sections as separate entities introduces bugs and nasty discrepancies, e.g.:
   • transparent sections do not reparent their subsections
   • subsection sorting is missing
   • subsection pagination isn’t a thing
   • get_section() is missing lang option
   • taxonomies for sections are missing
   • subsections are missing many useful fields, e.g. summary, date, update_date (requested here)
2. The user’s code is duplicated. I run {% set item = page | default(value=section) %} in shortcodes and macros to enable them both for sections and pages. This is not perfect, since atm their fields are slightly different.
3. Users sometimes want to have sections nested under pages.

Page vs. Section

The actual difference between these two is minor:
Pages are missing these fields:

• pages: Array<Page>
• subsections: Array<String>
• generate_feed: bool

Sections are missing:

• date: String?
• updated: String?
• slug: String
• draft: Bool
• summary: String?
• taxonomies: HashMap<String, Array<String>>
• lower: Page?
• higher: Page?
• year: Number?
• month: Number?
• day: Number?
• colocated_path: String?

IMO, if we remember that sections can have markdown, then most of the fields are worth adding anyway, which makes them very similar.

On the other hand, bringing pages to parity with sections looks fairly trivial

Documentation complexity and cognitive load

I hear the arguments that it’s easier for a user to digest familiar concepts section=folder and page=file and then operate on this, but later this fires back, as shown in the Issues section of this post.

We can safely assume that Zola’s users are at least somewhat familiar with how HTML and websites work. And for web developers, everything is a page. Many have already created index.html to represent a “folder” and colocated pages for individual “files”, so the new concept should be even more natural than the filesystem analogy.

I suggest that instead of “sections and pages” we explain it like this:

Page can be an individual file: post.md
Page can be a directory: post/index.md
Page can have subpages: post/subpost.md

It’s easier to remember than meaningful underscores in filenames, IMO

Backwards compatibility

Of course, we mustn’t break the existing websites by any means. We can achieve backwards compatibility by:

1. Adding all missing section’s fields to the page. The subsections field can be hidden, but present
2. In terra context aliasing section to page
3. Treating _index.md like a normal page, but with template="section.html" property. This will allow to distinguish between sections and pages for users who prefer it this way

After a couple of versions which warn users of using deprecated sections and page fields, we can drop the compatibility, but leave #3, as it seems like a good idea regardless.

Proposal

So, the actual plan is scoped and straightforward:

1. Add Section functionality to Page, i.e. these fields
   • generate_feed
   • subpages
2. Add aliases:
   • context.section → context.page
   • page.pages → page.subpages
   • get_section() → get_page()
3. Add a compatibility field page.subsections, which will list subpages with children
4. Handle _index.md to correspond to a page with template="section.html"

Alternatives

One small adjustment can be that any page with subpages would use section.html template by default, but that’s to be discussed.

Outro

This was a bit hectic post, but hopefully, I made my points clear. I do believe that unifying sections and pages into a single entity will improve Zola’s code base, user experience, and unlock new use cases without sacrificing anything.

Please, let me know what you think about this, any feedback is appreciated

[HugoTrentesaux]

Wow!! I like a lot the way you describe the problem and bring smart suggestions for backward compatibility. The section vs page distinction was annoying when writing templates and I frequently had to implement workarounds like this or duplicate code like that. If you successfully implement this refactoring in Zola, I will write a new theme specifically for this update

[spence]

Your proposal makes sense and is pretty thought out. One thing though that I didn’t see addressed, probably because it’s not something that’s represented by variables but is rather a convention, is that page paths and section paths are slightly different.

The difference is that page paths get slugified with dates removed if a date is in either the page file name or the directory name. Sections don’t do this. This is a problem that I’m currently dealing with.

In any case, honestly, as someone who uses Zola a lot, the page vs. section thing is actually needlessly complex. It would be better if there was just a super set of both. But I don’t know the details and I’m happy to change my opinion.

Having them behave more similarly though would probably make things easier for new comers and power users.

[keats]

I believe this has been proposed many years ago already like the link you mentioned and probably in a few other places. There are some people (like me) that do like them separated. I’m not opposed to it though if the end result is more coherent/easier to use.

You still need the concept of directories those, eg for a feed. Adding a feed to every page doesn’t make sense. I’d also like to have current sections with colocated assets to work eventually. In practice it could mean keeping the current distinctive file names but filling all the fields + having a single name for it in the templates (this/self) would solve 95% of the issues

It’s easier to remember than meaningful underscores in filenames, IMO

The only reason for the leading _ is that the files are shown at the top of the folder so you don’t have to search around when you have hundreds of pages at the same level.

Perf wise, it’s also better to have the concept of sections since you can parallelise on that. Even if we don’t expose it we will have to have the concept internally.

[bemyak]

Thanks for your reply! I really appreciate you considering this!

You still need the concept of directories those, eg for a feed. Adding a feed to every page doesn’t make sense.

I agree that “leaf” pages having a feed sounds a bit niche. That’s why there’s the generate_feed property that will be moved from sections and set to false by default. People who still want to have such a feed (e.g. for comments on a page) are free to enable it and build a template to deal with it.

The only reason for the leading _ is that the files are shown at the top of the folder so you don’t have to search around when you have hundreds of pages at the same level.

Nice, I didn’t know that! But at least for me it doesn’t work like that, because when you have post-directories they come on top, so I still have to skim through the list to find the index file.

Perf wise, it’s also better to have the concept of sections since you can parallelise on that. Even if we don’t expose it we will have to have the concept internally.

I’m not sure I’m following. Currently, we first deal with the site structure (populate_taxonomies, populate_sections), and then render markdown. The rendering happens in parallel for pages, and then in parallel for sections:

getzola/zola/blob/e9485ef3960d03b00510727a7486b113106c916b/components/site/src/lib.rs#L431-L456

So, having only pages will make it even more parallel

Sure, we need to distinguish between leaves and non-leaves during page graph modifications (what is now called populate_sections), and we can even expose an additional field, e.g. is_leaf or has_children to streamline page.subpages.is_empty() call.

[keats]

But at least for me it doesn’t work like that, because when you have post-directories they come on top, so I still have to skim through the list to find the index file.

Yep doesn’t work in that case but it does for a lot of text-{only/mostly} content like a lot of blogs/documentation.

That part is only the markdown rendering. The HTML rendering is parallelized over sections because you need to handle things like pagination, feed

[nikhilweee]

I would like avoiding underscores if I can.

[alexandremjacques]

I’m new to Zola (loving it, btw). I ended up here looking for info to understand what “Section” would mean semantically. I wasn’t find a good reason for it to exist (I could find not so good ones).

I’m building a news portal for a small community and sections were something that categories, or even tags, would cover. It wasn’t making much sense to have them in the first place.

So, in my newbie opinion, drop’em. I would like, though, to keep some kind of folder organisation inside content (which I think, folders without the Section semantic, would suffice).

Thanks for the great generator.

[oyam]

I’ve recently converted a few sites from variety of generators including some custom-built ones and the page/section concept is something that’s caused me the most grief.

I like the proposal and wanted to add an extra voice behind it. I’ve seen a few from the past, and was always sad to see there was no follow through.

Being anble to distinguish section (eg. Index/list) from a leaf page is important to me, but as was mentioned in the proposal, an is_leaf property would be sufficient for that. Similarly, it would actually be useful to be able to generate per-page feeds, so the ability to control that via a property would be great.

Thanks for the well thought out proposal, and thanks Keats for creating Zola!

[bemyak]

Thanks for the feedback! I’m glad that people found my arguments reasonable.

I like the proposal and wanted to add an extra voice behind it. I’ve seen a few from the past, and was always sad to see there was no follow through.

To be clear, I am going to work on the implementation, but I have some stuff going on in my life right now. Hopefully, it’ll be solved by February and then I can start the refactoring. It’s a big change indeed, and I’d really like to hear more feedback on the proposal. @keats is not opposed to it, but I need to be sure that I don’t break anything and not introduce any regressions for it to be merged.

If someone else wants to implement it, please go ahead.

[keats]

I would probably want to wait a bit more before implementing it. First we need Tera 2 to be in a usable state because it’s also going to change some of the usage a bit and we can release one version that will be the base for future Zola (1.0.0?).

[adrianboston]

I’m against this idea. The word section didn’t gel with me for a bit. But i got over it.

A group of ducks are ducks. duck ducks
A bunch of gooses are geese. goose geese
Mice are a bunch of mouses. mouse mice
A group of pages are pages… page pages

call it a pages, page group or page index. sure introduce some of those fields.

one fair game i can think of in a blog is a series such as part 1, part 2, etc. those are within the typical one off blog posts.

[bemyak]

I fully agree that the concept of a “section” on a specific website/blog totally makes sense. My personal blog is also structured in sections, and I’ll keep it that way regardless of this proposal.

However, I don’t think there is one section implementation to fit all the use cases. A single website could have sections to:

• structure content in a directory-like hierarchy
• organize a series of posts
• keep a calendar-like structure (e.g. travel log)

All these use cases will require slightly different section implementation from the website author (a.k.a. Zola user). It’s up to them to determine how many section types in what flavour they want and if they need it at all.

So, in my opinion, a section is a representation-level concept. We should make it super-easy to implement, but not force the users into having them. In the engine, we will just list “co-located pages”, as we list co-located assets.

[adrianboston]

@bemyak

• structure content in a directory-like hierarchy
• organize a series of posts
• keep a calendar-like structure (e.g. travel log)

you mean outside of the typical weight and date ranking?
such as medium which is a sort of group of blogs

[HugoTrentesaux]

@bemyak

Hopefully, it’ll be solved by February

february 29^th is there, hope that your stuff is solved ^^

[bemyak]

I’m not working on it because as Keats mentioned, first we should switch to Tera 2. I’m not aware of the release timeline unfortunately.

But yeah, my stuff is pretty much solved

[tcldr]

Love this proposal. It seems to dovetail neatly with what appears to be the Zola foundation of power through simplicity. This proposal seems to enhance that philosophy. It will eliminate a few conditionals that I’ve already accumulated and make shortcode and template reuse that more intuitive.

I understand the concern that the separation between ‘pages’ and ‘sections’ is a useful conceptual aid to help beginners, but ‘pages’ with optional ‘subpages’ seems far closer to how Zola operates in practice.

With the help of some good ‘getting started’ documentation that demonstrates how a site can evolve from a single page website to a blog, I think people would quickly take to it.