# Proposal: Deprecate sections **URL:** \ **Category:** Feature requests\ **Created:** [December 14, 2023, 9:36am UTC](https://zola.discourse.group/t/proposal-deprecate-sections/1968 "2023-12-14T09:36:00Z")\ **Posts on this page:** 20\ **Page:** 1
**Author:** ![bemyak](https://yyz2.discourse-cdn.com/free1/user_avatar/zola.discourse.group/bemyak/32/1106_2.png) [@bemyak](https://zola.discourse.group/u/bemyak)\ **Post date:** [December 14, 2023, 9:36am UTC](https://zola.discourse.group/t/proposal-deprecate-sections/1968/1 "2023-12-14T09:36:00Z")
Yeah, I know, it sounds like a big change, but please hear me out šŸ™‚ Prior discussions: - [Section vs Page](https://zola.discourse.group/t/section-vs-page/522) ## 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](https://zola.discourse.group/t/should-transparant-sections-pass-their-subsections/1965/3) their subsections - subsection sorting [is missing](https://github.com/getzola/zola/pull/2372) - subsection pagination isnā€™t a thing - `get_section()` is [missing `lang`](https://github.com/getzola/zola/issues/2359) option - taxonomies for sections [are missing](https://zola.discourse.group/t/taxonomies-for-section/647) - subsections are missing many useful fields, e.g. `summary`, `date`, `update_date` ([requested here](https://zola.discourse.group/t/request-to-add-section-date-and-section-updated/761)) 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](https://zola.discourse.group/t/making-section-nested-under-page-keep-the-pages-path-even-if-it-has-a-date/1954) to have sections nested under pages. ## Page vs. Section The actual difference between these two is minor: Pages are missing these fields: - `pages: Array` - `subsections: Array` - `generate_feed: bool` Sections are missing: - `date: String?` - `updated: String?` - `slug: String` - `draft: Bool` - `summary: String?` - `taxonomies: HashMap>` - `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 šŸ™ ---
**Author:** ![HugoTrentesaux](https://yyz2.discourse-cdn.com/free1/user_avatar/zola.discourse.group/hugotrentesaux/32/105_2.png) [@HugoTrentesaux](https://zola.discourse.group/u/HugoTrentesaux)\ **Post date:** [December 14, 2023, 12:28pm UTC](https://zola.discourse.group/t/proposal-deprecate-sections/1968/2 "2023-12-14T12:28:01Z")
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](https://git.42l.fr/HugoTrentesaux/seagull/src/branch/master/templates/index.html#L21-L25) or duplicate code like [that](https://git.42l.fr/HugoTrentesaux/Albatros/src/branch/master/templates/section.html#L3-L6). If you successfully implement this refactoring in Zola, I will write a new theme specifically for this update šŸ˜» ---
**Author:** ![spence](https://yyz2.discourse-cdn.com/free1/user_avatar/zola.discourse.group/spence/32/1022_2.png) [@spence](https://zola.discourse.group/u/spence)\ **Post date:** [December 14, 2023, 2:05pm UTC](https://zola.discourse.group/t/proposal-deprecate-sections/1968/3 "2023-12-14T14:05:32Z")
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. ---
**Author:** ![keats](https://avatars.discourse-cdn.com/v4/letter/k/34f0e0/32.png) [@keats](https://zola.discourse.group/u/keats)\ **Post date:** [December 14, 2023, 2:07pm UTC](https://zola.discourse.group/t/proposal-deprecate-sections/1968/4 "2023-12-14T14:07:57Z")
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. ---
**Author:** ![bemyak](https://yyz2.discourse-cdn.com/free1/user_avatar/zola.discourse.group/bemyak/32/1106_2.png) [@bemyak](https://zola.discourse.group/u/bemyak)\ **Post date:** [December 14, 2023, 3:15pm UTC](https://zola.discourse.group/t/proposal-deprecate-sections/1968/5 "2023-12-14T15:15:39Z")
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: > 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. ---
**Author:** ![keats](https://avatars.discourse-cdn.com/v4/letter/k/34f0e0/32.png) [@keats](https://zola.discourse.group/u/keats)\ **Post date:** [December 15, 2023, 2:46am UTC](https://zola.discourse.group/t/proposal-deprecate-sections/1968/6 "2023-12-15T02:46:54Z")
> 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 ---
**Author:** ![nikhilweee](https://avatars.discourse-cdn.com/v4/letter/n/71e660/32.png) [@nikhilweee](https://zola.discourse.group/u/nikhilweee)\ **Post date:** [December 22, 2023, 1:51am UTC](https://zola.discourse.group/t/proposal-deprecate-sections/1968/7 "2023-12-22T01:51:19Z")
I would like avoiding underscores if I can. ---
**Author:** ![alexandremjacques](https://yyz2.discourse-cdn.com/free1/user_avatar/zola.discourse.group/alexandremjacques/32/1154_2.png) [@alexandremjacques](https://zola.discourse.group/u/alexandremjacques)\ **Post date:** [December 30, 2023, 5:26pm UTC](https://zola.discourse.group/t/proposal-deprecate-sections/1968/8 "2023-12-30T17:26:16Z")
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. ---
**Author:** ![oyam](https://yyz2.discourse-cdn.com/free1/user_avatar/zola.discourse.group/oyam/32/1167_2.png) [@oyam](https://zola.discourse.group/u/oyam)\ **Post date:** [January 15, 2024, 8:30am UTC](https://zola.discourse.group/t/proposal-deprecate-sections/1968/9 "2024-01-15T08:30:50Z")
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! ---
**Author:** ![bemyak](https://yyz2.discourse-cdn.com/free1/user_avatar/zola.discourse.group/bemyak/32/1106_2.png) [@bemyak](https://zola.discourse.group/u/bemyak)\ **Post date:** [January 15, 2024, 9:27am UTC](https://zola.discourse.group/t/proposal-deprecate-sections/1968/10 "2024-01-15T09:27:59Z")
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. ---
**Author:** ![keats](https://avatars.discourse-cdn.com/v4/letter/k/34f0e0/32.png) [@keats](https://zola.discourse.group/u/keats)\ **Post date:** [January 15, 2024, 10:24am UTC](https://zola.discourse.group/t/proposal-deprecate-sections/1968/11 "2024-01-15T10:24:26Z")
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?). ---
**Author:** ![adrianboston](https://yyz2.discourse-cdn.com/free1/user_avatar/zola.discourse.group/adrianboston/32/907_2.png) [@adrianboston](https://zola.discourse.group/u/adrianboston)\ **Post date:** [January 31, 2024, 4:19am UTC](https://zola.discourse.group/t/proposal-deprecate-sections/1968/12 "2024-01-31T04:19:52Z")
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. ---
**Author:** ![bemyak](https://yyz2.discourse-cdn.com/free1/user_avatar/zola.discourse.group/bemyak/32/1106_2.png) [@bemyak](https://zola.discourse.group/u/bemyak)\ **Post date:** [January 31, 2024, 2:01pm UTC](https://zola.discourse.group/t/proposal-deprecate-sections/1968/13 "2024-01-31T14:01:39Z")
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. ---
**Author:** ![adrianboston](https://yyz2.discourse-cdn.com/free1/user_avatar/zola.discourse.group/adrianboston/32/907_2.png) [@adrianboston](https://zola.discourse.group/u/adrianboston)\ **Post date:** [January 31, 2024, 4:22pm UTC](https://zola.discourse.group/t/proposal-deprecate-sections/1968/14 "2024-01-31T16:22:30Z")
> [@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 ---
**Author:** ![HugoTrentesaux](https://yyz2.discourse-cdn.com/free1/user_avatar/zola.discourse.group/hugotrentesaux/32/105_2.png) [@HugoTrentesaux](https://zola.discourse.group/u/HugoTrentesaux)\ **Post date:** [February 29, 2024, 12:00pm UTC](https://zola.discourse.group/t/proposal-deprecate-sections/1968/15 "2024-02-29T12:00:32Z")
> [@bemyak](#): > > Hopefully, itā€™ll be solved by February february 29th is there, hope that your stuff is solved ^^ ---
**Author:** ![bemyak](https://yyz2.discourse-cdn.com/free1/user_avatar/zola.discourse.group/bemyak/32/1106_2.png) [@bemyak](https://zola.discourse.group/u/bemyak)\ **Post date:** [February 29, 2024, 9:43pm UTC](https://zola.discourse.group/t/proposal-deprecate-sections/1968/16 "2024-02-29T21:43:57Z")
Iā€™m not working on it because as Keats [mentioned](https://zola.discourse.group/t/proposal-deprecate-sections/1968/11), first we should switch to Tera 2. Iā€™m not aware of the release timeline unfortunately. But yeah, my stuff is pretty much solved šŸ˜… ---
**Author:** ![tcldr](https://yyz2.discourse-cdn.com/free1/user_avatar/zola.discourse.group/tcldr/32/1188_2.png) [@tcldr](https://zola.discourse.group/u/tcldr)\ **Post date:** [March 3, 2024, 2:31pm UTC](https://zola.discourse.group/t/proposal-deprecate-sections/1968/17 "2024-03-03T14:31:20Z")
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. ---
**Author:** ![g-braeunlich](https://avatars.discourse-cdn.com/v4/letter/g/51bf81/32.png) [@g-braeunlich](https://zola.discourse.group/u/g-braeunlich)\ **Post date:** [July 27, 2024, 8:05am UTC](https://zola.discourse.group/t/proposal-deprecate-sections/1968/18 "2024-07-27T08:05:08Z")
Also would love to see this happen! zola fits my use cases amazingly well (big thanks for developing it!). The only rough edge for me was exactly this ā€œextra layer of complexityā€. As a newcomer, it took me some time to search through all the docs, finding no other solution (for my use case) than adding the boilerplate code `{% set item = page | default(value=section) %}` in many places mentioned above. In addition to the arguments outlined by @bemyak, I would like to add the following: - Like others in the above replies, I did not find the page/section concept in any other static page generator (e.g. pelican, vuepress). So I think, for people migrating from another tool, it would make life easier if this proposal would be accepted/implemented - By merging the 2 concepts, I strongly assume that maintainability of the codebase would improve a lot. Some follow up questions: > [@bemyak](#): > > Iā€™m not working on it because as Keats [mentioned](https://zola.discourse.group/t/proposal-deprecate-sections/1968/11), first we should switch to Tera 2. Iā€™m not aware of the release timeline unfortunately. > > But yeah, my stuff is pretty much solved šŸ˜… @keats My naive thinking: the tera 2 and section/pages look to me quite orthogonal / can be worked on independently. Whats the reason, why you first would like to see tera 2 done? Asking because e.g. @bemyak would have capacity now and usually peoples availability can change very quickly. Related offtopic: Is there a roadmap for zola / roadmap for tera? ---
**Author:** ![knzai](https://yyz2.discourse-cdn.com/free1/user_avatar/zola.discourse.group/knzai/32/1262_2.png) [@knzai](https://zola.discourse.group/u/knzai)\ **Post date:** [July 27, 2024, 7:46pm UTC](https://zola.discourse.group/t/proposal-deprecate-sections/1968/19 "2024-07-27T19:46:56Z")
Heck, Iā€™d love to see taxonomies also somehow have at least a consistent api with whatever sections/pages are, as well, for making breadcrumbs and whatnot, particularly some consistency re name verus title, ancestors, etc. My breadcrumbing is getting _complicated_ lol. ---
**Author:** ![keats](https://avatars.discourse-cdn.com/v4/letter/k/34f0e0/32.png) [@keats](https://zola.discourse.group/u/keats)\ **Post date:** [July 29, 2024, 2:07pm UTC](https://zola.discourse.group/t/proposal-deprecate-sections/1968/20 "2024-07-29T14:07:22Z")
> [@g-braeunlich](#): > > @keats My naive thinking: the tera 2 and section/pages look to me quite orthogonal / can be worked on independently. Whats the reason, why you first would like to see tera 2 done? Asking because e.g. @bemyak would have capacity now and usually peoples availability can change very quickly. > > Related offtopic: Is there a roadmap for zola / roadmap for tera? No roadmap. Tera2 is kinda ready ([GitHub - Keats/tera2](https://github.com/Keats/tera2)) but needs to be tested by actual users more (+ still missing some stuff). The main reason for waiting for that to be released first is because it could change a lot of how the Tera function look and Iā€™d rather have one big bang release that has all the breaking changes in one go rather than having 2 version with a lot of breaking changes. [Next page](https://zola.discourse.group/t/proposal-deprecate-sections/1968.md?page=2)