Zola 0.23 (Tera2) breaks the docs build — zola pin blocked at 0.22.1

[worktrunk-bot]

Zola 0.23.0 shipped Tera2 + refactoring, which replaces the templating engine. docs/ does not build under it, so the weekly CI pin bump for zola is blocked at 0.22.1 (the pin lives in ci.yaml and publish-docs.yaml). Filing rather than fixing because the replacement for macros is a design call, not a mechanical rewrite.

zola build against the official 0.23.3 x86_64-unknown-linux-gnu release binary fails on the first line of base.html:

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

Tera2 appears to have dropped the macro system outright — not renamed it. Probing a minimal site with the 0.23.3 binary, all four spellings fail: {% import "macros.html" as m %} and {% from "macros.html" import hello %} are both Unknown tag, {{ macros::hello(name="x") }} fails to parse at the : (Found ':' but expected }}), and even a {% macro %} block defined and called within a single template is Unknown tag. So there is no in-place substitution for ::; the shared partial has to be re-expressed some other way ({% include %} with context set at the call site is the obvious candidate, but that changes how arguments are passed).

The affected surface is small and fully enumerated:

• docs/templates/macros.html — defines the single toc_nav(docs_section, current_page) macro (55 lines)
• docs/templates/base.html:1 — the import, and :236 the call
• docs/templates/index.html:84 and docs/templates/page.html:7 — the other two calls

Those three :: call sites are the only ones in docs/templates/. What is not yet known is how much else in the other ~700 lines of templates Tera2 rejects — the build aborts at line 1 of base.html, so nothing past the import has been exercised. Whoever picks this up should expect to iterate: fix the macro, rebuild, and see what the next error is. A rendered-output diff against a 0.22.1 build is worth doing at the end, since a silently-changed filter or whitespace rule would not show up as an error.

Staying on 0.22.1 is fine for now — it builds and the docs publish — so this is not urgent. It only matters that the pin stops drifting silently, which the weekly renovation will otherwise keep reporting.

Reproduction

curl -sfL -o /tmp/zola.tar.gz https://github.com/getzola/zola/releases/download/v0.23.3/zola-v0.23.3-x86_64-unknown-linux-gnu.tar.gz
tar -xzf /tmp/zola.tar.gz -C /tmp
cd docs && /tmp/zola build

Minimal probe used for the four spellings above:

mkdir -p /tmp/zt/templates /tmp/zt/content
printf 'base_url = "https://example.com"\n' > /tmp/zt/config.toml
printf '{%% macro hello(name) %%}Hi {{ name }}{%% endmacro %%}\n' > /tmp/zt/templates/macros.html
printf '{%% import "macros.html" as m %%}\n<p>{{ m::hello(name="x") }}</p>\n' > /tmp/zt/templates/index.html
/tmp/zola --root /tmp/zt build

[worktrunk-bot]

The macro removal is real, but it is one of three independent breakages, and the "affected surface is small and fully enumerated" estimate in the description does not hold. The upstream 0.23.0 changelog is explicit — "shortcodes have been completely removed" — and that is the one that reaches into src/docs.rs, not just docs/templates/.

1. Tera2 template syntax. Four more breakages sit behind the macro import, each of which only surfaces once the previous one is fixed. All four are mechanical and I have a working patch (below): trim_end_matches(pat=…) → trim_end(pat=…), the filter filter is gone entirely, is starting_with("#") now needs is starting_with(pat="#"), and "…\s…" is rejected as an invalid string escape (\\s works). all four are confined to docs/templates/ and touch no Rust.

2. Shortcodes are gone. docs/templates/shortcodes/{terminal,rawcode}.html have no 0.23 equivalent, and {% terminal(cmd="…") %}…{% end %} is now Unknown tag. The blocker is that those invocations are generated — convert_dollar_console_to_terminal emits them into all 13 pages, so replacing shortcodes with Tera components means changing the Rust generator, test_docs_are_in_sync, and every snapshot that carries a terminal block. That is the design call, and it is a good deal larger than swapping the macro.

3. Content is now templated. 0.23 parses every .md through Tera, so the minijinja syntax worktrunk documents ({{ branch | hash_port }}, {{ vars.env | default(…) }}) is parsed as Zola template code. It fails loudly rather than silently — Variable 'branch' is not defined — which is the one piece of good news here, since 0.22.1 renders those literally and correctly today. The changelog points at skip_content_templating, but that is a per-file glob and does not rescue this repo: 8 of the 13 content files contain both documented minijinja examples and terminal blocks, so skipping templating for those files would disable the very rendering that has to be migrated in (2). Per-block {% raw %} wrapping is the only mechanism that separates them — and {% raw %} leaks literally under 0.22.1, so it cannot be staged ahead of the bump.

Net: the three have to land together. I am not opening a PR — (2) is a genuine design decision about the doc-generation pipeline rather than a rewrite I should pick for you, and a templates-only branch is worse than nothing because the Tera2 syntax in (1) breaks the currently-pinned 0.22.1 build, so it would redden main the moment it merged. Staying on 0.22.1 remains correct.

Verified template patch for (1) — applies cleanly, not committed anywhere

Confirmed against the official 0.23.3 x86_64-unknown-linux-gnu binary by rebuilding after each fix until the template layer stopped erroring. macros.html is renamed to toc_nav.html and included rather than called, with the two former arguments set as context variables immediately before the include (verified that {% set %} values are visible inside an {% include %}, and that false still short-circuits the is_current test). index.html's filter(attribute="slug", …) | first is replaced by get_page, which is a direct lookup rather than a scan over the section.

diff --git a/docs/templates/base.html b/docs/templates/base.html
--- a/docs/templates/base.html
+++ b/docs/templates/base.html
@@ -1,4 +1,3 @@
-{% import "macros.html" as macros %}
 <!DOCTYPE html>
 <html lang="en">
@@ -77,7 +76,7 @@
     {% if page.extra.canonical %}
-    <link rel="canonical" href="{{ config.base_url | trim_end_matches(pat='/') }}{{ page.extra.canonical }}">
+    <link rel="canonical" href="{{ config.base_url | trim_end(pat='/') }}{{ page.extra.canonical }}">
     {% else %}
@@ -85,7 +84,7 @@
-    <meta property="og:url" content="{% if page.extra.canonical %}{{ config.base_url | trim_end_matches(pat='/') }}{{ page.extra.canonical }}{% else %}{{ current_url | default(value=config.base_url) }}{% endif %}">
+    <meta property="og:url" content="{% if page.extra.canonical %}{{ config.base_url | trim_end(pat='/') }}{{ page.extra.canonical }}{% else %}{{ current_url | default(value=config.base_url) }}{% endif %}">
@@ -233,7 +232,8 @@
         {% set docs_section = get_section(path="_index.md") %}
-        {{ macros::toc_nav(docs_section=docs_section) }}
+        {% set current_page = false %}
+        {% include "toc_nav.html" %}
         {% endblock toc %}
diff --git a/docs/templates/index.html b/docs/templates/index.html
--- a/docs/templates/index.html
+++ b/docs/templates/index.html
@@ -81,15 +81,15 @@
 {% set docs_section = get_section(path="_index.md") %}
-{{ macros::toc_nav(docs_section=docs_section) }}
+{% set current_page = false %}
+{% include "toc_nav.html" %}
 {% endblock toc %}
@@ (content block)
 {# Display worktrunk content directly on homepage #}
-{% set docs_section = get_section(path="_index.md") %}
-{% set worktrunk = docs_section.pages | filter(attribute="slug", value="worktrunk") | first %}
+{% set worktrunk = get_page(path="worktrunk.md") %}
diff --git a/docs/templates/page.html b/docs/templates/page.html
--- a/docs/templates/page.html
+++ b/docs/templates/page.html
@@ -4,7 +4,8 @@
 {% set docs_section = get_section(path="_index.md") %}
-{{ macros::toc_nav(docs_section=docs_section, current_page=page) }}
+{% set current_page = page %}
+{% include "toc_nav.html" %}
diff --git a/docs/templates/shortcodes/terminal.html b/docs/templates/shortcodes/terminal.html
--- a/docs/templates/shortcodes/terminal.html
+++ b/docs/templates/shortcodes/terminal.html
@@ -19,8 +19,8 @@
-{%- set hl = raw | regex_replace(pattern="(?s)<pre[^>]*><code[^>]*>(.*)</code>\s*</pre>", rep="$1") | trim -%}
-{%- if cmd_line is starting_with("#") -%}
+{%- set hl = raw | regex_replace(pattern="(?s)<pre[^>]*><code[^>]*>(.*)</code>\\s*</pre>", rep="$1") | trim -%}
+{%- if cmd_line is starting_with(pat="#") -%}
diff --git a/docs/templates/macros.html b/docs/templates/toc_nav.html
rename from docs/templates/macros.html
rename to docs/templates/toc_nav.html
@@ -1,4 +1,9 @@
-{% macro toc_nav(docs_section, current_page=false) %}
+{# Sidebar navigation. Include it, don't call it: Tera2 (Zola 0.23+) dropped
+   macros, so the two arguments arrive as context variables the call site sets
+   immediately beforehand.
+
+   docs_section — the section whose .pages become the nav entries
+   current_page — the page to mark active and expand a TOC under, or false #}
 <div class="toc">
@@ -52,4 +57,3 @@
 </div>
-{% endmacro toc_nav %}

Tera2 builtin inventory, and how the rest was established

The supported-name lists were read from the pinned dependency rather than probed, so they are exhaustive rather than a sample. Zola 0.23.3 pins tera = "2.0.0"; register_filter/register_test/register_function in tera-2.0.0/src/tera.rs plus Zola's own components/templates/src/filters/ give:

• Filters — abs capitalize default double escape_html escape_xml first float get group_by indent int join keys last length lower newlines_to_br nth pairs pluralize replace reverse round safe shout sort split str title trim trim_end trim_start truncate unique upper values wordcount, plus Zola's base64_decode base64_encode date filesizeformat format json_encode markdown num_format regex_replace shuffle slugify spaceless striptags urlencode urlencode_strict. Note the absence of filter, map, concat, and trim_end_matches.
• Tests — array bool containing defined divisible_by ending_with even float integer iterable map none number odd starting_with string undefined. Arguments are keyword-only now, which is what breaks starting_with("#").
• Tags — import, from, and macro are all Unknown tag; include extends block filter set set_global if for raw all still parse.

Auditing docs/templates/ against those lists found every remaining breakage in one pass instead of one rebuild at a time, and ad/od/skipped in that audit are false positives out of the inline JS and a code comment.

For (3), the 0.22.1-vs-0.23.3 difference was isolated on a two-file scratch site: identical input renders <code>{{ branch }}</code> literally under 0.22.1 and errors under 0.23.3. {{/* … */}} is not an escape in 0.23 (it fails at the /); only {% raw %} works, and it round-trips both inline spans and fenced blocks correctly. A scratch pass that mechanically wrapped every fence and span containing {{/{% in {% raw %} got the whole site past the content layer and straight into the shortcode failure in (2), which is what pins (2) as the remaining blocker rather than something further down.

Counts behind the "8 of 13" claim, as minijinja-in-code | terminal-blocks per file: config.md 73|52, hook.md 68|5, tips-patterns.md 52|17, extending.md 41|4, llm-commits.md 25|3, step.md 4|46, faq.md 3|9, list.md 3|8. The remaining five (claude-code, merge, remove, switch, worktrunk) carry terminal blocks only.

A rendered-output diff against 0.22.1 is still worth doing at the end, as the description says — I captured a 14-page 0.22.1 baseline but there is nothing to compare it against until (2) lands.

[max-sixty]

ok, let's fix please; use your judgement

[worktrunk-bot]

Done — #3840 migrates the site and bumps the pin to 0.23.3. All three breakages land together, as the analysis above said they'd have to.

The one place my earlier comment was wrong: components replace macros as well as shortcodes, so the "no in-place substitution for ::" conclusion doesn't hold. {% component toc_nav(…) %} … {% endcomponent %} called as {{ <toc_nav docs_section={docs_section} /> }} is a direct swap, and the same mechanism covers terminal — including calls from markdown content, which is what the generated terminal blocks need. So (2) turned out not to be the design call it looked like: src/docs.rs emits {% <terminal cmd="…"> %} instead of {% terminal(cmd="…") %} and nothing about the doc-generation pipeline changes shape. rawcode only ever wrapped its body in a <code class="multiline">, so it's deleted and the four table cells carry that element directly.

For (3), {% raw %} wrapping is generated rather than authored: wrap_template_syntax in src/docs.rs wraps the lines and fenced blocks that carry template syntax, strip_template_syntax_wrappers reverses it, and the sync test strips on read and wraps on write. So docs/content/*.md is still authored and compared without the markers, and the skill/README renderings come out byte-identical to before.

Two breakages the earlier audit didn't reach, both only visible once the template layer stopped erroring:

• \ is Tera2's string-escape character, so a shell continuation inside cmd="…" was an unexpected escape character build error — and a sequence Tera2 does recognise would have been rewritten silently. It gets a __WT_BSLASH__ placeholder alongside the existing three.
• Highlighting classes changed from scope names to palette indices (z-l-<n> / z-d-<n>), which breaks the two custom.scss rules that named scopes, and the theme CSS now goes to the output directory instead of docs/static/.

Rendered output was diffed page by page against a 0.22.1 build: no content differences — only entity spelling, whitespace, and <pre> no longer nesting inside <p>. check-docs passes on 0.23.3, as do the three platform test jobs and codecov/patch.