[BUG] Zola 0.23

[stockholmux]

Describe the bug

Zola 0.23 makes a breaking change to the templating engine. We either need to document that people should use 0.22 or move the templates away from macros to make it comply with 0.23 (thanks @rlunar)

To Reproduce
Try to build the site with 0.23

Expected behavior
It builds.

Screenshots
n/a

Host/Environment (please complete the following information):
n/a

Additional context

n/a

[pnbrown]

Zola 0.23 ships Tera v2, which is a rewrite.

The migration is substantial:

Macros are completely gone, replaced by components (different syntax, no import, global registration, JSX-ish call syntax).
Undefined variable access now errors instead of silently passing.
No my_vec.0 array access; must use my_vec[0].
Many filter renames (as_str→str, escape→escape_html, divisibleby→divisible_by, etc.).
include ... ignore missing removed.
Content with Tera syntax now needs {% raw %} wrapping (per the 0.23 zola notes).

The real work is:

28 macro definition lines (14 macros across 2 files) to convert to components
8 files with {% import %} to rewrite
~9 macro call sites to convert to component-call syntax
At least one filter rename: escape → escape_html in
docs.html
Plus the undefined-variable-errors behavior change, which can surface at runtime on many pages and is the hardest to predict without building.

Converting Jinja2 macros to Tera v2 components changes both the definitions and every call site, the call syntax is different ({{<commands.foo arg="x"/>}} instead of {{ commands::foo(arg="x") }}), and macros that call other macros or take array/object args need rework. On top of that, 0.23's "undefined access errors" rule will likely surface failures on the command and docs pages that only appear once the templates parse. Those pages also depend on the sibling repos (valkey-doc, valkey) being linked in

[pnbrown]

Letting my agents churn with this design doc before testing and tweaking:

Migrating valkey.io from Zola 0.22 (Tera v1) to Zola 0.23 (Tera v2)

Status: in progress, on branch migrate-zola-0.23
Audience: maintainers reviewing the migration pull request

Summary and context

The valkey.io website is built with Zola, a static site generator whose templating is provided by the Tera engine. Zola 0.23.0 ships Tera v2, and the Zola 0.23.0 release notes describe it as the most breaking Zola release to date: Tera moved from v1 to v2, and the old shortcode mechanism was removed. Our templates use several Tera features that v2 changed or removed, so the site stopped building on 0.23. To keep developing in the meantime, the toolchain was held at Zola 0.22.1.

The goal of this work is narrow and concrete: build cleanly on Zola 0.23.x while producing byte-for-byte the same rendered HTML the 0.22.1 build produces. This is a template-syntax migration, not a redesign. No page should look or read differently after the change; only the template source that generates those pages changes.

Why not switch to a different static site generator

A framework switch (for example to Astro) is out of scope. The reason is the shape of the work, not a judgment about Astro. This is a bounded, mechanical migration of Tera template syntax within the generator we already use. The site's content pipeline is the hard part, and none of it is generic Zola: the command reference, documentation topics, and clients page are all injected at render time from sibling repositories (valkey, valkey-doc, valkey-bloom, valkey-json, valkey-search) through load_data against symlinks, and site search is a post-build fuse.js index produced by build/build-search-index.mjs over the rendered public/ HTML. Moving generators would mean reimplementing that injection pipeline and the search indexer from scratch, which is a much larger effort with far more risk than adapting the templates. We keep Zola and adapt to Tera v2.

Background: how this site leans on Tera

Most Zola sites use Tera lightly, for layout and a handful of filters. This repo uses it as a small programming language, and that is why the Tera v2 changes land harder here than they would elsewhere.

Three patterns show up repeatedly in the templates:

• Macros used as value-returning helpers. templates/macros/command.html and templates/macros/docs.html defined macros whose rendered output was captured into a variable with {% set x = docs::helper(...) %} and then fed into later logic. Examples include load (reads a topic Markdown file), extract_frontmatter and extract_markdown (split a document on ---), fix_links (a long chain of regex_replace calls), and the path builders such as command_json_path.
• Recursive argument parsing. arguments_parse in command.html walks the nested arguments array of a command's JSON and calls itself (self::arguments_parse) to render oneof and block groupings. Command syntax lines are built by this recursion.
• Accumulation and map-key extraction. List pages build up arrays with concat, slice arrays with the slice filter, and extract the single top-level key of a command JSON object (the command name) by iterating the map.

Every one of those patterns touches something Tera v2 changed. That is the crux of the migration.

Tera v2 breaking changes that affect this repo

The Tera v1 to v2 migration guide is the reference for what changed. The changes below are the ones that broke this repo, each paired with the construct it broke and the replacement we chose.

Macros are removed and replaced by components

Tera v2 removes macros and the {% import ... as ... %} mechanism that brought them into a template. In their place it introduces components, defined with {% component name(args) %}...{% endcomponent name %} and called with the shortcode-style syntax {{< name arg={value} />}}. Components are registered globally, so the per-template {% import "macros/command.html" as commands %} and {% import "macros/docs.html" as docs %} lines are deleted and every commands:: or docs:: call site is rewritten as a component call.

Concretely, templates/macros/command.html and templates/macros/docs.html now define components rather than macros, and call sites change form:

• {{ docs::boolean_to_checkmark(value=json_data[field]) }} becomes {{< boolean_to_checkmark value={json_data[field]} />}}.
• {{ docs::format_language(language=language) }} becomes {{< format_language language={language} />}}.

The recursive arguments_parse keeps its recursion, but the recursive call changes from self::arguments_parse(...) to the component call {{< arguments_parse argument_array={arguments.arguments} separator="|" />}} captured into next. Recursion works because components are globally registered and can call themselves by name.

Value-returning helpers become set-capture blocks

Tera v2 components render output; they do not return a value the way the old macros were used to. Several helpers here were consumed as values, for example {% set docs_file_contents = docs::load(slug=page.slug) %}. The v2 pattern for capturing rendered output into a variable is the set-capture block: {% set x %}...{% endset %}. So a value-returning helper call becomes a component call wrapped in a set-capture block:

{% set docs_file_contents %}{{< load slug={page.slug} />}}{% endset %}

This applies to load, extract_frontmatter, extract_markdown, and fix_links across docs.html, docs-page.html, topics-list.html, and command-page.html.

One consequence of capturing rendered output is leading and trailing whitespace. Where the captured value is measured (frontmatter detection compares its length against zero), the migration adds a | trim after the capture so an all-whitespace capture reads as empty, matching the old macro's behavior. This appears as {% set frontmatter = frontmatter | trim %} in docs.html, docs-page.html, and topics-list.html.

concat is removed in favor of the spread operator

Tera v2 removes the concat filter. List accumulation that read list | concat(with=[item]) is rewritten with array-literal spread, [...list, item]. The list templates use {% set_global commands_entries = [...commands_entries, command_entry] %} and {% set_global topics_entries = [...topics_entries, topic_entry] %}, and docs.html uses the same form for its JSON-string accumulator.

slice is removed in favor of native slicing

Tera v2 removes the slice filter and adds native slicing on arrays, arr[2:]. docs.html's extract_markdown previously read content | split(pat="---") | slice(start=2) | join(sep="---"). It now splits into a variable first and slices natively:

{%- set parts = content | split(pat="---") -%}
{{ parts[2:] | join(sep="---") }}

escape is renamed to escape_html

Tera v2 renames the escape filter to escape_html. The topic description in docs.html changes from frontmatter_data.description | escape | safe to frontmatter_data.description | escape_html | safe.

Undefined access now errors, with one level of tolerance

Tera v2 makes accessing undefined values an error rather than silently yielding an empty value, with one level of undefined-ness allowed and optional chaining (a?.b) and guards available for deeper access. In practice the existing templates already guard the deep accesses they depend on (for example arguments.type and arguments.token before reading arguments.token, and command_data_obj.container before using it), so this change mostly validates that those guards are correct rather than forcing large edits. Where a captured value is later tested, the | trim and length checks described above keep the access within the one allowed level.

Command-name extraction uses keys | first

The old command_obj_name macro found a command JSON object's single top-level key (the command name) by looping the map and capturing the key into a global. Tera v2 makes that indirection unnecessary and the macro form invalid, so it is replaced inline with command_data | keys | first. This appears in command-page.html, commands.html, and command-list.html.

Design decisions and rationale

Path-builder helpers are inlined rather than turned into components. The macros command_json_path, command_bloom_json_path, command_json_json_path, command_search_json_path, and client_json_path each returned a single string such as config.extra.command_json_path ~ slug ~ ".json". Two of their call sites build that string inside an array literal, for example the four-element json_path list iterated in commands.html and command-list.html, and the command_sources list in command-page.html. A component call cannot be used to produce a value inside an array literal (the set-capture pattern that replaces value-returning helpers is a statement, not an expression), so wrapping these as components would not work where they are needed most. Inlining the concatenation directly, config.extra.command_json_path ~ page.slug ~ ".json", is both valid in that position and clearer than the indirection it replaces. The path values themselves still live in config.toml under [extra] (command_json_path, command_bloom_json_path, command_json_json_path, command_search_json_path, command_description_path, client_json_path, doc_topic_path), so nothing about configuration changes; only the string assembly moves from a macro into the call site.

Value-returning helpers that are consumed as whole strings (not inside array literals) use set-capture blocks. load, extract_frontmatter, extract_markdown, and fix_links each produce a block of text that is assigned to one variable and then piped onward, so the {% set x %}...{% endset %} form fits them directly.

Recursion is preserved by keeping arguments_parse a component and having it call itself by name. Because components register globally, {{< arguments_parse ... />}} inside arguments_parse resolves to the same component, which is exactly the behavior the old self::arguments_parse provided. The command syntax lines that this recursion renders are unchanged.

Affected files

File	What changed
templates/macros/command.html	arguments_parse and fix_links converted from macros to components; recursion via {{< arguments_parse ... />}}; command_obj_name and the four path-builder macros removed (inlined at call sites).
templates/macros/docs.html	load, extract_frontmatter, extract_markdown, fix_links, boolean_to_checkmark, format_language converted to components; extract_markdown uses native slice parts[2:]; client_json_path macro removed.
templates/command-page.html	import removed; command source paths inlined; command_obj_name replaced by keys | first; arguments_parse and fix_links called as components inside set-capture blocks.
templates/commands.html	import removed; four json_path entries inlined; command_obj_name replaced by keys | first; concat replaced by spread.
templates/command-list.html	import removed; four json_path entries inlined; command_obj_name replaced by keys | first; concat replaced by spread.
templates/docs.html	import removed; load, extract_frontmatter, extract_markdown, fix_links called via set-capture blocks; escape renamed to escape_html; concat replaced by spread.
templates/docs-page.html	import removed; helpers called via set-capture blocks; frontmatter | trim added before the length check.
templates/topics-list.html	import removed; load and extract_frontmatter called via set-capture blocks; frontmatter | trim added; concat replaced by spread.
templates/client-feature-table.html	import removed; client JSON path inlined; boolean_to_checkmark called as a component.
templates/client-list.html	import removed; client JSON paths inlined; format_language called as a component.

Verification plan

Verification has three parts: the build must succeed on the new Zola, the rendered HTML must match the 0.22.1 baseline, and the search index must still regenerate at a comparable size.

Build. zola build on Zola 0.23.6 must complete with no template errors. Because the external content is injected at render time, a meaningful build requires the sibling repos linked locally per the README's "Building additional content" steps (./build/init-topics-and-clients.sh and ./build/init-commands.sh). The build symlinks (build-command-json, build-topics, build-clients, and the bloom, json, and search command-json links) must be present so the command, topics, and clients pages render with real content rather than the empty-state fallbacks.

Output parity. Build once on 0.22.1 to capture a baseline public/, build again on 0.23.6, and diff the two trees. The content stubs in this repo give exact expected counts to check against: 437 command stubs under content/commands and 86 topic stubs under content/topics (the clients page renders from valkey-doc/clients). Beyond counts, spot-check the pages that exercise the migrated code paths:

• The GET and SET command pages, whose "Usage" line is produced by the recursive arguments_parse component; confirm the rendered argument syntax is identical to the baseline.
• The topics index (/topics/) and the /topics-list/ fragment, which exercise load, extract_frontmatter, the escape_html rename, and the spread accumulator.
• The clients page and its feature comparison table, which exercise format_language, boolean_to_checkmark, and the inlined client JSON paths.

Search index. After a disk build on 0.23.6, npm run build must regenerate public/search-index.json with a record count comparable to the 0.22.1 baseline. The deploy workflow already enforces a floor (MIN_RECORDS = 1500, with the real count noted there as roughly 2,100 because long pages are split per h2 section) and checks that at least one /topics/ and one /commands/ record carry content. Running the same check locally confirms the migration preserved the rendered HTML structure the indexer reads.

Open item found during migration

templates/client-list.html still contains {% set_global languages = languages | concat(with=language) %} in the Table of Contents loop. concat is removed in Tera v2, so this line must be converted to the spread form ([...languages, language]) before the build will pass. It is called out here so the reviewer confirms it is fixed in the final PR rather than assuming the import and component edits already covered it.

Rollout and risk

Single pull request, not a stack. Zola stops at the first template error, so a partially migrated tree does not build; there is no intermediate state that compiles. Splitting the change across several PRs would leave every PR before the last one unbuildable, so the template edits ship together.

Version bump in the same PR. The deploy workflow (.github/workflows/zola-deploy.yml) pins the build to shalzz/zola-deploy-action@v0.22.0, which selects the Zola version used in CI. That pin must move to the action release that runs Zola 0.23.x in the same PR as the template edits, because the templates only build on 0.23 and the old action only builds the pre-migration templates. Bumping them separately would break main in one direction or the other. [DATA NEEDED: exact shalzz/zola-deploy-action release tag that bundles Zola 0.23.6.]

Interaction with the in-flight search work. Site search is being changed on a separate branch. The two efforts do not conflict: the search indexer depends only on the structure of the rendered public/ HTML (page titles, h2 sections, visible body text), and this migration preserves that HTML exactly. As long as output parity holds, the indexer sees the same input before and after the migration, so the search branch is unaffected and the two can merge in either order.