Skip to content

feat: highlight code with Zola instead of highlight.js - #18

Merged
magnus-madsen merged 3 commits into
masterfrom
feat/server-side-syntax-highlighting
Aug 9, 2026
Merged

feat: highlight code with Zola instead of highlight.js#18
magnus-madsen merged 3 commits into
masterfrom
feat/server-side-syntax-highlighting

Conversation

@magnus-madsen

@magnus-madsen magnus-madsen commented Aug 9, 2026

Copy link
Copy Markdown
Member

Closes #7.

The issue asked whether highlighting could move to a sublime-style grammar. It can move off highlight.js, but not to .sublime-syntax: Zola 0.22 (which this repo already runs) replaced syntect with giallo, so extra grammars are VSCode/TextMate JSON and the config moved into [markdown.highlighting]. Feeding it the Flix.sublime-syntax from flix/talks fails with a JSON parse error.

The grammar it does want already exists: flix/textmate, which flix.dev consumes the same way. Both sites now colour Flix from one grammar.

What changes

  • syntaxes/flix.tmLanguage.json is vendored, byte-identical to flix/textmate at the pinned GRAMMAR_COMMIT, so a clone builds with nothing but Zola. make update-grammar refreshes it after bumping the SHA, and the result lands as a reviewable diff.
  • Colours come from Catppuccin Mocha, which Zola generates into static/giallo.css. That is the family tabi's own syntax stylesheet was derived from, and its ground (#1E1E2E) and base text (#CDD6F4) sit right where tabi had them — with 381 rules behind it instead of tabi's 65.
  • Deletes the 22K highlight.js bundle, its activation script, and the two hand-written stylesheets. themes/tabi/templates/partials/header.html is stock again, so tabi updates no longer need re-patching.
  • Both build outputs (syntaxes/flix.tmLanguage.json, static/giallo.css) are gitignored.

What it looks like

Nine colours across the blog's Flix blocks, against four under the old setup; operators, escapes and language constants are distinguished for the first time. Scala, shell, Rust and Markdown blocks are highlighted at all for the first time — highlight_activate.js had to force nohighlight on everything except Flix, because the bundle carried only the Flix grammar.

Trade-offs worth reviewing

  • Language badges change. Zola labels blocks with the resolved grammar name, so ```sh now reads SHELLSCRIPT, and ```claude, ```prompt and ```txt (15 blocks) read PLAIN. Renaming those fences is a follow-up if the labels matter.
  • Function names and stdlib calls lost their colour. highlight.js guessed at them from a word list; flix/textmate has no entity.name.function or support.function rules, so no theme can recover them. Fixing that upstream would benefit flix.dev too.
  • A 9KB vendored file can drift from flix/textmate until someone bumps the SHA and runs make update-grammar. The alternative — fetching at build time — was tried first and dropped: it made make mandatory, and Windows ships no make, so it would have cost Windows contributors the plain zola serve workflow they have today.
  • Changing the theme needs static/giallo.css deleted by hand. Zola writes that file only when it is absent, so the old colours otherwise survive a rebuild and a running zola serve. Documented in the README rather than handled in the Makefile, which would have cost portability on every build for something done once a year.

Verified: clean-tree make builds in 0.4s, a second make is idempotent, and CI needs no change — the workflow already runs make.

🤖 Generated with Claude Code

magnus-madsen and others added 3 commits August 9, 2026 09:24
Code blocks were highlighted in the browser by a highlight.js bundle
carrying only the Flix grammar, which meant every other language had to be
opted out of highlighting entirely -- Scala, shell, Rust and Markdown blocks
rendered as plain text.

Zola highlights them at build time instead, using the TextMate grammar from
flix/textmate that flix.dev already uses, so both sites now colour Flix from
one grammar. `make` fetches it, pinned to a commit for reproducibility.

The colours come from Catppuccin Mocha, generated by Zola into
static/giallo.css: the same family tabi's own syntax stylesheet was derived
from, and near the value tabi gave code blocks before, but with 381 rules
behind it rather than 65. Operators, escapes and language constants are
distinguished for the first time.

Zola 0.22 replaced syntect with giallo, so extra grammars are VSCode JSON
rather than .sublime-syntax, and the highlighting options moved into
[markdown.highlighting].

Drops 22K of vendored JS, the two hand-written stylesheets that shadowed it,
and the local patch to tabi's header.html -- the theme is stock again.

Closes #7

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
`mkdir -p` and `rm -f` are not commands cmd.exe has, and GNU Make only picks
sh.exe when one happens to be on PATH -- so a contributor who installed make
without Git Bash or WSL hit a failure on the first recipe line.

curl --create-dirs makes the directory itself, and the giallo.css cleanup is
gone: it existed so a theme change would take effect, which is rare enough to
document rather than pay for on every build.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Windows ships no make -- not in cmd.exe, not in PowerShell, and not with Git
for Windows -- so requiring `make` to assemble the tree meant a contributor
had to install a build tool the OS has never carried, where `zola serve` used
to be the whole workflow.

The grammar is now committed at syntaxes/flix.tmLanguage.json, byte-identical
to flix/textmate at the pinned commit, so a clone builds with nothing but
Zola. `make update-grammar` refreshes it after bumping GRAMMAR_COMMIT, and the
result arrives as a reviewable diff rather than an invisible pin.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
@magnus-madsen
magnus-madsen merged commit 403725c into master Aug 9, 2026
2 checks passed
@magnus-madsen
magnus-madsen deleted the feat/server-side-syntax-highlighting branch August 9, 2026 07:37
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.

Use textmate grammar instead of highlight.js

1 participant