Upgrading to Zola version 0.23

Last weekend I ran a brew upgrade on my laptop and noticed that running zola build on my personal site (what you're reading right now) didn't work anymore.

Trying to get the whole thing to work again required looking up the Zola and Tera documentation and their migration guide. In this post, I'll give a quick walkthrough of the errors I ran into and how I was able to get past them.

1. Replacing macros with components

The first error I ran into looked like this:

ERROR Failed to build the site
ERROR error: Unknown tag
 --> base.html:1:4
  |
1 | {% import "macros.html" as macros %}
  |    ^^^^^^

Zola uses Tera as the underlying templating engine. And Zola version 0.23 switched from Tera version 1 to version 2. Version 2 contains a number of breaking changes, the one relevant to this error being the removal of macros in favor of components.

To fix this, you need to replace your macro definitions with component definitions and adjust the usage accordingly.

For instance, if you had a macro defined like this:

{% macro example(args) %}
{{ args }}
{% endmacro %}

{% example(args="hello world") %}

You'll need to replace it with an equivalent component definition, e.g.

{% component example(args) %}
{{ args }}
{% endcomponent %}

{{ <example args="hello world" />}}

So essentially you need to change a little bit of syntax and things should work again.

2. Escape template syntax in post content

With that fixed, the build got a little furthe before failing again.

ERROR Failed to build the site
ERROR Failed to render page content of '/path/to/post/index.md'
ERROR Reason: error: Unknown tag
  --> __tera_one_off:43:58
   |
43 | So, I installed [django-htmx] in my project, added a `{% htmx_script %}` to the base
   |                                                          ^^^^^^^^^^^

This happens because Zola (or Tera?) sees the {% htmx_script %} in the post content and tries to render it, but fails because it's Django template syntax instead of Tera syntax.

The fix is to just wrap inline Tera syntax inside a {% raw %} block.

3. Fixing sort order in page list

Fixing the two errors above got me a working build. The next issue I noticed was that the /posts page was rendering the post list in some arbitrary order. The relevant piece of code from the template file looked like this:

{% for year, posts in section.pages|group_by(attribute="year") %}
...
{% endfor %}

It's supposed to group all the posts by the year they were written in and display the list in reverse chronological order. I didn't spend enough time investigating what attribute the post list was sorted on, but it definitely wasn't publication time.

Luckily, Tera's documentation had a fix:

{% set map = section.pages | group_by(attribute="year") %}
{% set_global years = [] %}

{% for year, ignored in map %}
    {% set_global years = [...years, year] %}
{% endfor %}

{% for year in years | sort | reverse %}
    {% set posts = map[year] %}
    ...
{% endfor %}

And that did the trick!

All in all, the upgrade to Zola 0.23 was quite painless. While the breaking changes were unexpected, Zola's and Tera's migration guides covered everything that I ran into, and the fixes themselves were mostly mechanical. If you're upgrading your own site, hopefully this saves you a bit of time!