Enable looping over sections or page/section colocation

My site is being generated by Zola. Its structure is roughly this:

  • front page [page / section] →
    • category [section within root/index/content folder] →
      • project [page within category] →
        • related pages [page???]

Ideally, related pages would also be hosted as pages within projects. This is where the conundrum that renders this suggestion begins.

Zola is clear about the separation of sections and pages, as well as about disallowing both to exist under the same namespace. It would then make sense to render projects as sections with section.content etc., except one can’t simply loop over sections in the same way one does over pages.

Looping over section while maintaining access to their data requires anchoring the section in a variable within the loop, making in-loop actions (such as sorting by a section attribute) impossible. Section-based loops (for project in category.subsections) only return verbal links to said sections (/writing/sentience/_index.md), not section objects themselves, which is (1) confusing, (2) less useful than expected.

So far, I’ve tried making a page and a pseudo-section for the same project. This works for Zola, but doesn’t for me, because I can’t realistically access semi-dynamic content without hardlinking it within the template. (I can’t be expected to feed every new chapter of the book, for example, to the template: this kind of manual work being tedious is why things like Zola exist.) I can’t, in this configuration, render files from the pseudo-section out of the same-name page’s template, even though the two ultimately collide.

The questions I’d like to raise are:

  • is there a good reason the separation between pages and sections is as strong as it’s enforced to be?
  • is it possible to automatically enable the same page + section status from the front page to all pages if necessary?

Ideally, I’d like to be able to use a page (/content/writing/sentience.md) for content, and a colocated section (/content/writing/sentience/) for any additional, hierarchically-inferior pages.This makes sense in terms of precompiled content structure: pages go to the same level as their containing categories, – and allows the developer to access and manipulate content they already mentally connect as one. It also makes a degree of sense regarding HTML hierarchy, where folders form “categories” by their very nature.

Alternatively, I’d like to be able to form categories automatically out of a folder, an index.md files (sans initial underscore), and any set of included folders or Markdown files. This makes less sense from the standpoint of Zola’s current structure, and makes more sense from the standpoint of the resulting HTML structure, aligning preproduct with product mentally.

Barring either of those, I’d like to be able to loop over sections with the same ease and to the same result as looping over pages. I’m sure this is the easiest of the three to implement. I question whether this is preferable, but then I’m not the one reifying Zola, so I yield final judgement to @keats.

I’d also be eager to discuss options not mentioned in this post. My goal is to be able to produce content with Zola as I envision it. Methods, unless convoluted or complicated, are irrelevant.

The reason you can’t iterate on sections like you do for pages is performance. For the template engine we need to serialize all the content to JSON which is already kind a bottleneck in the current state. Allowing that would really destroy performance for large sites

The way I see it, you either enable a powerful-but-demanding feature you can optimize later, or you take an obvious opportunity away from the user.

As a regular guy who just wants to build stuff without installing tons of support software or following convoluted instructions, I’ll gladly take a hit of 10 seconds per build in order to make the process obvious and easy for myself. That’s the reason I chose Zola over a dozen other options: it’s simple to use, it’s clear in instruction, and it works as you’d expect… except for these small things.

As a developer, I get it. I spend days optimizing my own software: I simply can’t afford to release software that isn’t up to my own rigid standards. It’s not just my reputation at stake: it’s the fact that I release another bloated, convoluted app into the world. Fuck that.

But here’s a user who’s otherwise satisfied with your software, asking you to enable a potentially-cumbersome feature that may or may not eventually get optimized, because they’d rather have a clear development process than an immediate build. What do you do?

Besides: you could enable it with a warning. “This feature is very slow at the moment, and is only suitable for small sites”. This puts the power into user’s hands, letting them choose which direction they want to take their development in.

I’ve been thinking further about the page/section colocation.

The only reason I’m unable to fully utilize it is because the section _index.md file isn’t automatically created for folders which ultimately share name with an independent page. (Say, /writing/sentience/ folder and the /writing/sentience.md file.) Therefore, I couldn’t reliably access the folder’s orphan pages without linking to specific ones manually.

Could it be made so that pages could access shared-namespace folders without the page/section conflict?