Colas.Nahaboo.net - zola

Invent your own HTML tags!

2026-08-31T00:00:00+00:00

The HTML spec has had a proper way to invent your own tags since 2019. Most web developers seem to have missed it.

Want a simple way to have a word in blue? just use <ink-blue>word</ink-blue>

My migration of this site to Zola Tera 2 forced me to rethink shortcodes and ad-hoc styling, which is what prompted me to dig into §4.13 of the HTML standard for the first time. I found three pieces, all now supported by every current engine.

What?🔗

Custom elements are an old idea — Chrome shipped a v0 API in 2014, the cross-browser v1 standard followed a few years later. The pattern is straightforward: extend HTMLElement, register the class via customElements.define(). The simplest example, lifted from the spec, is a country-flag icon:

class FlagIcon extends HTMLElement {
  constructor() {
    super();
    this._countryCode = null;
  }
  static observedAttributes = ["country"];

  attributeChangedCallback(name, oldValue, newValue) {
    this._countryCode = newValue;
    this._updateRendering();
  }
  connectedCallback() {
    this._updateRendering();
  }
  get country() { return this._countryCode; }
  set country(v) { this.setAttribute("country", v); }
}
customElements.define("flag-icon", FlagIcon);

And use it as:

<flag-icon country="nl"></flag-icon>

The only rule I had to learn the hard way: the name must contain a hyphen. <flag-icon> works; <flagicon> does not. The hyphen is the spec's way of ensuring your tag can never collide with a future native one.

Three lifecycle hooks do most of the heavy lifting — connectedCallback, disconnectedCallback, attributeChangedCallback. There is also adoptedCallback (when your element moves documents) and the newer connectedMoveCallback (added so the element keeps its state when moved inside the DOM without being disconnected). That is all there is to it.

ElementInternals🔗

This is the piece that surprised me the most. Set one static field and call one method, and your custom element behaves like a real form control — it appears in form.elements, submits values, has validity, willValidate, and labels. It also carries default accessibility semantics, so screen readers treat your tag like the proper role without you attaching ARIA manually:

class MyCheckbox extends HTMLElement {
  static formAssociated = true;
  static observedAttributes = ["checked"];

  constructor() {
    super();
    this._internals = this.attachInternals();
    this._internals.role = "checkbox";
    this._internals.ariaChecked = "false";
    this.addEventListener("click", this._onClick.bind(this));
  }

  attributeChangedCallback(name, oldValue, newValue) {
    this._internals.setFormValue(this.checked ? "on" : null);
    this._internals.ariaChecked = this.checked;
  }

  get checked() { return this.hasAttribute("checked"); }
  set checked(flag) { this.toggleAttribute("checked", Boolean(flag)); }
  _onClick() { this.checked = !this.checked; }
}
customElements.define("my-checkbox", MyCheckbox);

A nice extra: this._internals.states.add("checked") plus the CSS :state(checked) pseudo-class lets you flip states from JavaScript and style them with CSS, no attribute-flipping dance.

ElementInternals has been Baseline widely available since March 2023.

Declarative Shadow DOM🔗

The piece I missed most. <template shadowrootmode="open"> inside your custom element lets the shadow tree be rendered from pure HTML — no JavaScript required for the initial render:

<my-component>
  <template shadowrootmode="open">
    <style>p { color: tomato }</style>
    <p>Hello from a shadow root</p>
  </template>
</my-component>

For static sites this is a game changer — Zola, Hugo, plain Markdown — your shadow tree ships as part of the HTML, the browser wires it up at parse time. No flash of unstyled component, no JS bundle needed.

When upgrading from HTML that contains a declarative shadow root, check ElementInternals.shadowRoot first — if it is already populated, your markup already shipped the tree and you should not call attachShadow() again.

Browser support landed between March 2023 and February 2024 — Chrome 111+, Safari 16.4+, Firefox 123+. There is also shadowrootclonable and shadowrootdelegatesfocus for cloning and focus delegation. See the Declarative Shadow DOM guide on web.dev for the details.

Closing🔗

Three pieces, all in the HTML spec, all shipped in every current browser. The only thing missing was awareness. So, awareness raised — we no longer have any excuse to keep reinventing component frameworks. :-)

Migration of this site to the new Zola Tera2

2026-08-06T00:00:00+00:00

I migrated this site to Zola 0.23, released yesterday with the new Tera 2 template engine (Well, 0.23.1 from today actually). When I chose Zola last March, I praised its creator for not chasing the latest fad. I stand by it: 0.23 breaks my templates, but it does it in a cleaner way.

Tera 2 removes the old macros and imports, and Zola 0.23 removes the shortcodes. Everything is now a namespaced component. A macro that I used to import and call like this:

{% import "macros.html" as utils %}
{% macro show_link(url) %}<a href="{{ url }}">{{ url }}</a>{% endmacro %}
...
{{ utils::show_link(url=link) }}

is now a global component with no import at all:

{% component site.show_link(url) %}<a href="{{ url }}">{{ url }}</a>{% endcomponent %}
...
{{<site.show_link url={link} />}}

The big philosophical change: components are global and no longer inherit the caller context. Every variable — page, section, config, current_path — must be passed explicitly as an argument. More verbose, but it makes dependencies visible. I like that more and more: one way to do it, and it is visible.

Tera 2 is also strict: a missing variable is now a hard error. My templates use optional chaining (?.) for anything optional, which catches typos at build time instead of silently rendering broken pages.

What concretely changed:

concat and slice filters are gone → array spread and slicing
get_env is gone → config.mode == "serve" for local editor links
include ... ignore missing is invalid → empty hook templates
get_page with fatal=false → canonical path with lang and allow_missing=true
get_taxonomy_url with name → term

The migration guide was my best map through all of this.

I use the Apollo theme as a git submodule, and as it does not support Zola 0.23 yet, I keep a small local template-only patch of it until upstream migrates. The design, CSS, and JavaScript are untouched: this was a syntax migration, not a redesign, and I did not rewrite my post contents either.

Use of AI🔗

I chose to have AI help me migrate my site. It worked flawlessly, so I encourage you to do the same. AI work especially well with Zola, as it is opinionated, and that means that there are clear ways of doing things so that AI agents do not get lost in rabbit holes trying to pursue all the possibilities of more flexible systems like Hugo.

For reference here is the first prompt I gave it to prepare the plan for the migration:

I want you to only create a document for agents ai/agents/tera2.md to summarize
how tera2 of Zola 0.23 differs from tera1 of Zola 0.22, and the plan to migrate
my site from Zola 0.23 to 0.22.

Examine the differences between Zola 0.22 and 0.23, not just tera.

Docs:
Tera2 https://keats.github.io/tera/
Migration guide Tera1 → Tera2 https://github.com/Keats/tera/blob/master/MIGRATION.md
Zola 0.23 docs https://www.getzola.org/documentation/getting-started/overview/

Take your time, be thourough, but do not modify yet any file of my site except
the ones in ai/agents/ and AGENTS.md

Then, plan the migration of this site to zola 0.23
1. not modifying the contents of the posts unless necessary for tera2 changes
2. not changing the look and feel, the UI of the site
3. adapting the various templates
4. changing my local copy of the Apollo theme I use if needed.
   These changes are a stopgap measure until upstream apollo is migrated to Zola 0.23

I use Deepseek v4 flash normally, but chose to use GPT-5.6 Luna for this migration as it is currently quite cheap and I trust it more to not go change unecessary files. And Deepseek as no vision, so it cannot check the actual visual results of changes. It helped me greatly for this migration, without any problems.

Summary of AI actions:🔗

Replaced Tera 1 macros, imports, self:: calls, and macro namespaces with namespaced Tera 2 components in the root templates and Apollo templates.
Converted the local language-listing, page, navigation, debug, file inclusion, and section-name helpers to components.
Converted the site shortcode implementations to components in templates/macros/shortcodes.html.
Converted active post calls from the removed Zola shortcode syntax to Tera 2 component syntax. This includes YouTube, snapshots, attachments, Mermaid, static-file inclusion, legacy overlays, obsolete notices, and SVG icons.
Passed explicit base_path values to components that used to receive page.path implicitly from Zola shortcodes.
Updated get_page calls to use the canonical path with lang="fr" and allow_missing=true.
Updated get_taxonomy_url calls from name to term.
Replaced the removed get_env call with config.mode == "serve" for the local editor links.
Replaced the removed concat and slice filters with Tera 2 array spread and slicing, and changed the object test to map.
Added empty Apollo hook templates because Tera 2 no longer accepts include ... ignore missing.
Updated dev/bin/site-check to recognize the new legacy component syntax.
Updated static/ZOLA to zola 0.23.0.

Converting Zola pages from TOML to YAML

2026-04-07T00:00:00+00:00

Since Zola now supports frontmatter in its markdown pages in the YAML format in addition to the original TOML, I decided to migrate all my pages to YAML, as it is both easier to read and write for humans, and natively understood by a majority of tools (Emacs, marktext, obsidian, vs-code, typos, zettlt...)

So I wrote a small bash script for the conversion, site-toml2yaml (all my personal site management tools start with the prefix site- for taking advantage of the tab-completion). It should run on any Linux or Unix system, and it requires dasel and the usual gang: grep, sed, head...

Note that you could also use hugo convert, but I haven't tested it.

You can grab it at my zola-tools repository. This repository is quite empty for now, but I will use it to publish the various small tools I use to maintain this public site.

Usage🔗

site-toml2yaml md-files or directories...

Converts in place the frontmatter of Markdown files from TOML to YAML.
It recurses in directories, but looking only for *.md files and sub-dirs.
Without argument, run on ${ZOLA_ROOT}/content/
Should work on any Markdown files with TOML frontmatter.

You should only run it on your content/ dir normally. For instance running it on your themes/ dir will risk messing your imported themes

WARNING: it modifies the files in place, so MAKE A BACKUP before running it!

Why converting to YAML?🔗

TOML is arguably a better configuration file format than YAML, but only if you want to use it as a simpler JSON, i.e. a well-specified, unambiguous way to represent any data.

However, I feel that for the simple and limited use case of Zola pages frontmatter, it is overkill and thus a real pain to read and edit by hand. Let's take an example:

TOML

[table1]
    foo = "bar"

    [table1.nested_table]
        baz = "bat"

[[comments]]
author = "Nate"
text = "Great Article!"

[[comments]]
author = "Anonymous"
text = "Love it!"

YAML

comments:
  - author: Nate
    text: Great Article!
  - author: Anonymous
    text: Love it!
table1:
  foo: bar
  nested_table:
    baz: bat

See? Especially for people like me with a Unix culture, the YAML format seems both more natural (resembling the format of email or HTTP headers, the use of indentation à la Python), and TOML has a repulsive Windows flavor. Add to this that most of the tools I use understand natively YAML frontmatter but not TOML, and the decision is easy.

A new version of the site for 2026, in Zola

2026-03-19T00:00:00+00:00

I said that I wanted to migrate this web site to a SSG (Static Site Generator). And, after 5 years of procrastination, Ta-Da! here is the new site!

Initially, I was planning to use Hugo, since I love coding in Go, and was not planning to learn Rust (Hugo is coded in Go and Zola in Rust), but I finally chose Zola over Hugo for many reasons:

Zola has basically all the performance advantages of Hugo, and is also a single binary, with no need for databases, docker, snap, flatpak...
Zola is opinionated. This is very important for me, I love more and more the systems were there is "only one way to do it". Needless to say, I hate perl, and I love Go.
Zola is stable, and its creator ("Keats") very committed to not chasing the latest fad. This means less risk of an upgrade breaking things.
Zola template engine, Tera, is both more powerful and more readable than the standard Go template engine used by Hugo.
Zola comes with more useful built-in features, but no plugins that in my opinion brings complexity, especially in docs, and upgrade hell.

As for the theme, I was looking for a clean responsive modern simple theme, with high scores in the various web performance benchmarks, with search and comments, and some support for multilingual (the site is in English with a few pages also translated in French). I tried the two leaders in the Zola theme ecosystem:

Tabi I liked the looks but it felt a bit too complex for my needs: as a Zola novice I was afraid to end up relying too much on Tabi-specific feature instead of pure Zola and CSS ones.
ABridge I liked the architecture, not so much the design, but I struggled to make it work, it seems the doc still advise settings that break on recent Zola versions.

I thus looked for a simpler theme, and chose:

Apollo which was perfect for my needs, and simple enough to be easily modified for any of my future needs. I also enabled its support for the Giscus commenting system.

Porting my contents was made easy because I had anticipated this migration, and used Markdown for my posts in the Foswiki engine, instead of the native Foswiki syntax. So converting was basically adding a frontmatter to the pages, and fixing some links. I converted older posts with pandoc.

I have made a quick first migration. I will continue working on the CSS architecture and the looks in the following weeks.

Update on 2026-03-22: I now am satisfied of the result. I plan to work a bit more to add a search for only the French pages (now the search ignores them), autodetection of the browser light/dark preferences, sort the tags alphabetically in the page info line.