Skip to content

chore: bump Zola to 0.22.0 (Giallo highlighting migration)#2

Merged
n-WN merged 1 commit into
mainfrom
chore/bump-zola-0.22
Jun 1, 2026
Merged

chore: bump Zola to 0.22.0 (Giallo highlighting migration)#2
n-WN merged 1 commit into
mainfrom
chore/bump-zola-0.22

Conversation

@n-WN

@n-WN n-WN commented Jun 1, 2026

Copy link
Copy Markdown
Member

Summary

Bumps the build toolchain from Zola 0.21.0 to Zola 0.22.0 and performs the required highlighting-config migration.

Zola 0.22.0 replaces the Syntect syntax highlighter with Giallo (see the getzola/zola CHANGELOG). This is a breaking change: all highlighting options move from [markdown] into a new [markdown.highlighting] table, and highlight_theme is gone. Without this migration the site fails to build (unknown field highlight_theme / unknown field highlight_code).

Production deploys ship the artifact built by deploy-cloudflare-pages.yml (Cloudflare Pages does not rebuild), so that workflow's Zola version is authoritative and is bumped here. test-build.yml is aligned to the same version.

Config change (config.toml)

Before:

[markdown]
highlight_code = true
bottom_footnotes = true
# To use a Zola built-in theme, CSP needs to allow unsafe-inline for style-src.
highlight_theme = "css"
smart_punctuation = true

After:

[markdown]
bottom_footnotes = true
smart_punctuation = true

[markdown.highlighting]
highlight_code = true
theme = "catppuccin-frappe"
style = "class"

Notes:

  • highlight_code had to move into [markdown.highlighting] (0.22.0 rejects it under [markdown]; the build error itself listed the valid [markdown] fields).
  • highlight_theme = "css" is replaced by style = "class" (same effect: emit CSS classes, no inline colours) plus theme = "catppuccin-frappe". This matches the tabi 0.22 demo config.toml at the currently-vendored submodule commit 5c90004.
  • bottom_footnotes and smart_punctuation remain in [markdown] and continue to work.

Workflows

  • .github/workflows/deploy-cloudflare-pages.yml: step Install Zola 0.21.0 -> Install Zola 0.22.0, tool: zola@0.21.0 -> tool: zola@0.22.0.
  • .github/workflows/test-build.yml: shalzz/zola-deploy-action@v0.19.2 -> @v0.22.0 (the v0.22.0 tag exists and that action's tags track the Zola version; confirmed via the GitHub API). This also pulls the test build forward from the previously-lagging 0.19.2.

Verification (real local build, macOS arm64, official zola 0.22.0 binary)

  • zola build with the migrated config: exit 0, Creating 8 pages (0 orphan) and 4 sections, zero warnings. (For comparison, the 0.21.0/Syntect build emitted "Highlight language not found" warnings for text, verilog, and flag; under Giallo text and verilog no longer warn.)
  • Highlighting confirmed working: built HTML contains class="z-..." markup (e.g. z-keyword z-control, z-entity z-name z-function), and tabi's sass/parts/_syntax_theme.scss (compiled into main.css) defines those .z-* classes. So code blocks are styled, not left bare.
  • The previously-warned pages render highlighted: blog/hitcon2025 (verilog), blog/game0x2025w1 (text), and blog/idek2025-writeup (flag) all contain z- class markup.
  • KaTeX/math output present (katex.min.css emitted; katex markup in posts).

error_on_missing_language decision

Left OFF (omitted). Enabling error_on_missing_language = true was tested and turns a missing grammar into a hard build error:

ERROR Reason: Language `flag` not found for syntax highlighting in "blog/idek2025_writeup.md".
  • Unsupported-by-Giallo language found: flag (used in content/blog/idek2025_writeup.md). This is a made-up fence label, not a real language.
  • verilog and text, which warned under 0.21/Syntect, are accepted by Giallo and do not error.

Leaving the flag off keeps the build green. Follow-up (optional, not in this PR): change the flag fence to plain ``` (or text) and then error_on_missing_language could be enabled.

Risks for the reviewer

  • Colour shift possible. Giallo themes are not byte-identical to Syntect themes, and the class taxonomy changed. Because style = "class", actual colours come from tabi's _syntax_theme.scss, not from the theme value, so this should be minimal — but it is worth a visual spot-check of a code-heavy post.
  • Zola 0.22.0 also auto-emits a public/giallo.css. tabi does not link it (its templates load main.css), so it is dead weight in the output but harmless.
  • test-build.yml checks out submodules non-recursively (submodules: true). tabi has a nested submodule; the deploy workflow uses submodules: recursive. This is pre-existing and unchanged here, but if the test-build job fails on a missing nested submodule that predates this PR.

Not verified

  • The two GitHub Actions workflows were not executed; only the local zola 0.22.0 build was run. The v0.22.0 shalzz tag and the zola@0.22.0 install-action target were confirmed to exist but the runners' end-to-end behavior was not exercised.

Zola 0.22.0 replaces the Syntect highlighter with Giallo and moves all
syntax-highlighting options from [markdown] into [markdown.highlighting].

- config.toml: move highlight_code into [markdown.highlighting]; replace
  highlight_theme = "css" with style = "class" and theme =
  "catppuccin-frappe" (matching the tabi 0.22 demo). Output stays
  CSS-class based, coloured by tabi's own stylesheet.
- deploy-cloudflare-pages.yml: install-action zola@0.21.0 -> zola@0.22.0.
- test-build.yml: shalzz/zola-deploy-action@v0.19.2 -> @v0.22.0.

error_on_missing_language is left off: the 'flag' code fence in
content/blog/idek2025_writeup.md has no Giallo grammar and would fail the
build. Verified locally with a real zola 0.22.0 build (exit 0).
@n-WN n-WN merged commit 2e1f755 into main Jun 1, 2026
2 checks passed
@n-WN n-WN deleted the chore/bump-zola-0.22 branch June 1, 2026 06:24
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant