Section vs Page

The more I’m using Zola, the less I understand the difference between a section and a page. A section is basically just a page with subpages so why differentiating it ?

My “sections” are pages with subpages and deserve date, taxonomies as well… I think these two should be merged. What are the reasons to keep them separated ?

I think it’s easier to have the two concepts separated for documentation rather than having just some comment saying there is a specific file called which allows to control pagination etc. It’s also easier to name things, eg a section has pages and subsections but if everything is named page it’s harder to understand imo.

You’re right and I think that’s the whole point. There is no reason separating both in terms of functionality but when it comes to explaining how to use zola, it’s very useful to introduce two concepts.

Here is a detail of the front-matter of page only, section only, and both:

# page
date =
updated =
draft = false
slug = ""
path = ""
# section
sort_by = "none"
page_template =
paginate_by = 0
paginate_path = "page"
insert_anchor_links = "none"
render = true
redirect_to = 
transparent = false
# both
title = ""
description = ""
weight = 0
in_search_index = true
template = "some.html"
aliases = []

Here is a detail of the variables available in a template for page only, section only, and both:

# page
date: String?;
year: Number?;
month: Number?;
day: Number?;
updated: String?;
slug: String;
draft: Bool;
summary: String?;
taxonomies: HashMap<String, Array<String>>;
earlier: Page?;
later: Page?;
heavier: Page?;
lighter: Page?;
# section
pages: Array<Page>;
subsections: Array<String>;
# both
content: String;
title: String?;
description: String?;
path: String;
components: Array<String>;
permalink: String;
toc: Array<Header>,
word_count: Number;
extra: HashMap<String, Any>;
translations: Array<TranslatedContent>;
lang: String;
relative_path: String;
ancestors: Array<String>;
assets: Array<String>;
reading_time: Number;

Right now I need my section to have taxonomies and the clean way to do that is to make it a page and to have a section to organize content. In the template, I have to load the section to get the content organization stuff. So I have a template mixing page and section. I think a cleaner way to do that is to have page and section the same object (lets call it “resource”) with the only difference that is a resource whose default template is section.html and or something else is a resource whose default template is page.html. In both templates, the resource will be available with the resource keyword so that template elements (like macros) can be reused for pages and sections.

You can look for example at the section (I ported the site from pelican). It has a breadcrumb feature allowing to browse between subsections and subpages as follows:


But I want it to benefit from the date and taxonomies today reserved to a page (here is a page example):

And I will have to compensate this lack of feature of a section by mixing page and section in my template. That’s an example which might be interesting later when thinking about the design :slight_smile:

Conceptually sections and pages are just a logical way of describing the relationships. A section is a collection of pages, simple.

Technically I get that a section is just a page (with some unique attributes) with a collection of child pages.

If you think sections should have taxonomies you should request it, but changing the concept of sections and pages makes no sense. Why clutter sections with dates for example? Or pages with paginate_path?

The same argument was made for TOC, it was missing in sections, someone made the case for it to be implemented and it was added.

The reality is the current implementation covers 80%+ of the use cases you will find on the web.

1 Like

As soon as sections have a content that can be written and read, there is a reason for them to have a ‘date’ and ‘updated’ attribute. I would like my readers to know how up to date they can expect the section content to be. Right now, I’m putting things like the list of authors or the date in the “extra” entry and I observe that my section and pages share so much templates elements that merging the two will help a lot.

I was just wondering if simplifying the concept will help in terms of software design. But apparently, the cost of having an unused ‘paginate_path’ in pages that are not sections (i.e pages without subpages) is too high.

In this case I will request sections to have date and taxonomies :slight_smile: