Hey all,
I keep having a problem where some of my pages end up blank for seemingly no reason. It seems random, but consistent, even when I rebuild from scratch. For instance, this page:
+++
title = "Choret: Choreographies as Macros"
date = 2025-06-04
[extra]
key = "Choret"
+++
# Abstract
Choret is an experimental implementation of choreographic programming as a library inside of [Racket](https://racket-lang.org/).
By using Racket macros, we are able to provide a traditional project-and-merge implementation of choreographies as an embedded DSL
# Source Code
The source code for Choret can be found on [github](https://github.com/Foundations-of-Decentralization-Group/choret).
is blank, while this page:
+++
title = "The Pirouette Language Compiler"
date = 2025-06-04
[extra]
key = "PirComp"
+++
# Abstract
We have been working on a compiler for a functional choreographic programming language based on [the original Pirouette paper](@/papers/pirouette/index.md).
This has served as both a research project and as a learning platform for undergraduates via the [UB CSE Experiential Learning and Research (EL/R) program](https://webdev.cse.buffalo.edu/elr/).
# Source Code
The source code for the compiler can be found on [github](https://github.com/Foundations-of-Decentralization-Group/Pirouette-Compiler).
is not.
Any idea why? How can I debug things like this?
Hi Andrew,
I read your post regarding a page that renders as blank and attempted to reproduce the issue on my end.
To test this, I mirrored your site’s structure based on the public version at akhirsch.science. I used Zola 0.20.0 and the zola-futu theme. My local directory was organized as follows:
content/
├── _index.md
├── papers
│ └── pirouette
│ └── index.md
└── posts
├── _index.md
├── choret-choreographies-as-macros
│ └── index.md
├── the-pirouette-language-compiler
│ └── index.md
└── welcome.md
Using the content fragments you provided, both the “Choret” and “The Pirouette Language Compiler” pages rendered successfully in my environment. The internal link to the Pirouette paper also resolved correctly.
Since the basic reproduction works, additional details might help identify why it is failing for you:
- Exact Zola version & theme commit hash: Are you using a specific version of Zola other than 0.20.0, and is the
zola-futu theme modified in any way?
- Terminal output: Do any
ERROR or WARNING messages appear in your terminal when you run zola serve?
- Page source: If you “View Page Source” on a blank page in the browser, is the HTML completely empty, or is there structure present without visible content?
If you can share your config.toml or any logs from the terminal, I can try to refine my local test case. Better yet: do you have a link to the site as a GitHub project, or something similar, that would enable me to reproduce the problem?
Hi,
Thanks for taking a look!
The github repo you mentioned is exactly the right thing. If you go to httlps://akhirsch.science, that website is built from that repo (automatically). If you go to https://akhirsch.science/projects/, that is a good example of the phenomenon I’m talking about. If you go to projects/pirouette-compiler, that works, while projects/choret that does not.
Zola version: it looks like I’m on zola 0.22.1. I just upgraded via snap, and the previous version had the same problem.
zola-futu version: I think I updated one of the templates inside of the zola-futu theme. I’m not sure what the best way to check that is.
Terminal Output: There is a warning about an orphan page on my current version, but I know why that is (I discovered the problem while trying to add a new page). On HEAD, there’s no warnings or errors.
Page source: as you can see on the pages above, I get the template code, but not any of the markdown code in place.
Hi Andrew,
I see the issue in the repo https://github.com/akhirsch/akhirsch.github.io: the choret/index.html has an empty <main> element, whereas pirouette-compiler/index.html contains the expected HTML.
Since that repo contains the build artifacts (the public folder), I can see the result but not the cause. I tried replicating your setup locally using the fragments from your post, but for me, both pages render correctly.
To find out why your build is skipping that content, could you share your source repository? I specifically need to see your config.toml, the content/ folder, and the changes you made to the zola-futu templates (if any).
If I can run your actual source files through Zola on my end, I should be able to spot exactly where the rendering breaks.
Ah, right, I forgot that that’s not the source repo.
You can find that at GitHub - akhirsch/professional-page
Hi Andrew,
your issue stems from a naming collision between your content directory and your defined taxonomies.
In your configuration, you have both a content directory named projects and a taxonomy named projects.
- Taxonomy pages are generated at
/projects/<term>/
- Content pages are generated at
/projects/<slug>/
Specifically, the page /papers/choreographies-as-macros/index.md assigns the taxonomy term projects = ["choret"]. Simultaneously, you have a content page at /projects/choret/. Because both attempt to occupy the same URL path, the taxonomy process takes precedence.
You can verify this by temporarily disabling the rendering of the projects taxonomy in your config.toml:
taxonomies = [
{ name = "area", feed = true },
{ name = "awards", feed = true },
{ name = "projects", render = false, feed = true } # Set render to false
]
After rebuilding, the content page at /projects/choret/ should appear correctly.
Solutions:
- Rename the Taxonomy (Recommended): change the taxonomy name from
projects to something distinct (e.g., topics or tags) that does not mirror a top-level content folder. This avoids the risk of path collisions.
- Namespacing (Zola 0.22.0 and later): since you mentioned you are on Zola 0.22.1, you can use the
taxonomy_root setting to move all taxonomies to a sub-folder, though this may require updates to your zola-futu. I got it only to work with Zola 0.20.0 without modifications.
# Move to /taxonomies/<taxonomy>/<term> instead of /<taxonomy>/<term>
taxonomy_root = "taxonomies"
Currently, Zola does not throw a warning for these collisions, which is why the build finishes without errors despite the overwritten files.
Thanks, that makes a ton of sense, and it worked when I tried it! Thanks very much.
Should I create an issue somewhere requesting that these sorts of name collisions cause a warning? That would have been very helpful when debugging this.