Actualitza el teu lloc tabi a Zola 0.23

Zola 0.23.0 ha canviat moltes coses, sobretot per l’actualització a Tera 2.

Com que això obliga els usuaris a fer canvis, he aprofitat per retirar opcions que només existien per compatibilitat amb versions anteriors. Aquest document pretén facilitar la transició.

tabi requereix Zola 0.23.6 o superior. Comprova la versiĂł que fas servir en local, a CI i al desplegament:

zola --version

Si necessites quedar-te en una versió de Zola anterior a la 0.23.0, fixa tabi a v4.2.0, l’última versió compatible.

Si ja tens un clon:

git -C themes/tabi fetch --tags
git -C themes/tabi checkout --detach v4.2.0
git -C themes/tabi describe --tags --exact-match

Com a submòdul:

git submodule update --init themes/tabi
git -C themes/tabi fetch --tags
git -C themes/tabi checkout --detach v4.2.0
git add themes/tabi
git diff --cached --submodule=log -- themes/tabi
git commit -m "Pin tabi v4.2.0 for pre-0.23 Zola"

El repositori pare desa el commit del submòdul, no el nom de l’etiqueta. Per a un clon nou:

git clone --branch v4.2.0 --depth 1 https://github.com/welpo/tabi.git themes/tabi

ĂŤndex

Elimina les opcions retirades

  • footnote_backlinks: fes servir [markdown].bottom_footnotes = true.
  • add_src_to_code_block: fes servir blocs de codi amb nom i code_block_name_links.
  • [extra].index_format: mou-la a [search] i a la taula de cerca de cada llengua activada.
  • translate_copyright i translated_copyright: fes servir copyright_translations.

Actualitza els formats de data

Si has configurat long_date_format, short_date_format, archive_date_format o date_formats, reescriu cada valor amb patrons UTS-35. Les directives % de strftime fallen quan tabi aplica la configuració regional de l’idioma.

# Abans
long_date_format = "%d %B %Y"

# Després
long_date_format = "dd MMMM y"

Les substitucions més comunes són %-d → d, %d → dd, %b → MMM, %B → MMMM i %Y → y. Escriu el text literal entre apòstrofs: d 'de' MMMM 'de' y.

Localitza què cal canviar

Cerca les crides a shortcodes en lĂ­nia:

grep -rEn --include='*.md' '[{][{][[:space:]]*[A-Za-z_][A-Za-z0-9_]*[[:space:]]*[(]' content

Cerca les crides a shortcodes de bloc:

grep -rEn --include='*.md' '[{]%[[:space:]]*[A-Za-z_][A-Za-z0-9_]*[[:space:]]*[(]' content

Cada resultat indica un fitxer, un número de línia i la crida. N’apareixeran de dos tipus:

  • Shortcodes com ara admonition, toc o dual_theme_image. Converteix-los a la sintaxi de components, tal com s’explica mĂ©s avall.
  • Funcions integrades com ara get_url, resize_image o get_taxonomy_url. Aquestes continuen funcionant a la 0.23. No les toquis.

Si vas envoltar exemples amb {% raw %}, aquests resultats sĂłn text literal. Tampoc no els toquis.

Llista els teus shortcodes i macros propis:

ls templates/shortcodes templates/macros

Tot el que hi aparegui Ă©s teu, no de tabi, i cal migrar-ho a templates/components/.

Revisa la configuraciĂł per trobar opcions retirades:

grep -En 'footnote_backlinks|add_src_to_code_block|translate_copyright|translated_copyright|index_format|highlight_code|highlight_theme' config.toml

Actualitza el realçat de sintaxi

Mou les opcions de realçat de [markdown] a [markdown.highlighting]:

[markdown]
smart_punctuation = true

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

Per fer servir temes diferents:

[markdown.highlighting]
light_theme = "catppuccin-latte"
dark_theme = "catppuccin-frappe"
style = "class"
error_on_missing_language = true

tabi requereix style = "class". Zola genera giallo.css, o bé giallo-light.css i giallo-dark.css.

Configura la cerca multilingĂĽe

La taula [search] de l’arrel configura la llengua per defecte. Cada llengua addicional amb build_search_index = true necessita la seva pròpia taula:

build_search_index = true

[search]
include_title = true
include_description = true
include_path = true
include_content = true
index_format = "elasticlunr_json"

[languages.ca]
title = "El meu lloc"
build_search_index = true

[languages.ca.search]
include_title = true
include_description = true
include_path = true
include_content = true
index_format = "elasticlunr_json"

Converteix els shortcodes en components

Les crides en línia perden els parèntesis i les comes:

-{{ admonition(type="tip", text="Stay hydrated") }}
+{{< admonition type="tip" text="Stay hydrated" />}}

Les crides de bloc fan servir etiquetes de tancament amb nom:

-{% admonition(type="tip") %}
+{% <admonition type="tip"> %}
 Stay hydrated.
-{% end %}
+{% </admonition> %}

Envolta entre claus les expressions, els booleans, els nombres, els arrays i els mapes. Per defecte, els paràmetres dels components són explícits. Prefixa amb @ els paràmetres de context ambiental a la definició del component perquè Tera els resolgui des del cridador:

{% component post_language(@lang: string) %}
{{ lang }}
{% endcomponent post_language %}
{{< dual_theme_image light_src="light.webp" dark_src="dark.webp" full_width={true} />}}
{{< multilingual_quote original="Hola" translated="Hello" />}}
{{< iine />}}

Migra els teus shortcodes propis

Mou les plantilles del teu lloc de templates/shortcodes/ a templates/components/ i defineix un component. Aquest exemple està adaptat d’un lloc que fa servir tabi:

{% component youtube(id: string, class = "", playlist = "", autoplay = false) %}
<div{% if class %} class="{{ class }}"{% endif %}>
    <iframe src="https://www.youtube-nocookie.com/embed/{{ id }}{% if playlist %}?list={{ playlist }}{% if autoplay %}&amp;autoplay=1{% endif %}{% elif autoplay %}?autoplay=1{% endif %}" allowfullscreen></iframe>
</div>
{% endcomponent youtube %}
{{< youtube id="dQw4w9WgXcQ" class="video" autoplay={true} />}}

Fes servir parĂ metres normals per a les entrades del component i parĂ metres implĂ­cits per a valors ambientals com lang, config o page. Un valor implĂ­cit encara es pot sobreescriure explĂ­citament al lloc de la crida.

Protegeix els exemples literals

El markdown es processa com a plantilla abans de renderitzar els blocs de codi. Envolta els exemples literals entre {% raw %} i {% endraw %} al fitxer font.

Els identificadors d’encapçalament personalitzats no necessiten blocs raw:

## Comprovacions de desplegament {#comprovacions-de-desplegament}

Fes servir skip_content_templating només quan el fitxer sencer hagi de saltar-se el processament de plantilles.

Revisa les teves plantilles personalitzades

Les plantilles pròpies que sobreescriuen les del tema, a templates/, no s’actualitzen amb el tema.

AbansAra
macros i {% import %}components
items | concat(with=item)[...items, item]
items | slice(start=1)items[1:]
value | as_strvalue | str
trim_start_matches / trim_end_matchestrim_start / trim_end
item.0item[0]
is starting_with("http")is starting_with(pat="http")
is iterable per a arraysis array
get_taxonomy_url(..., name=term)get_taxonomy_url(..., term=term)
{% include "x" ignore missing %}inclou un fitxer per defecte que existeixi

L’accés a valors indefinits és més estricte. Fes servir encadenament opcional, com ara page?.extra?.setting, i comprova els valors nuls explícits abans d’aplicar-hi filtres. default(value=...) gestiona els valors indefinits, no els nuls.

get_page i get_section reben una ruta canònica i lang. Els arguments dels components fan servir literals de cadena o expressions entre claus; page és la forma abreujada de page={page}.

Consulta la guia de migraciĂł de Tera per veure tots els canvis del llenguatge.

Diferències esperades a la sortida

  • Notes al peu: etiquetes entre claudĂ tors i enllaços absoluts amb fragments #fn-* i #fr-*.
  • Realçat: classes de tokens numerades z-*, o bĂ© z-l-*/z-d-*.
  • Espais en blanc: hi ha diferències al voltant de la sortida dels components; revisa el contingut en lĂ­nia i els aniuaments.
  • Ordre de les llengĂĽes: pot canviar l’ordre del selector de llengua i dels hreflang; les destinacions no haurien de canviar.
  • XML: l’escapament pot variar, tot i que els valors descodificats continuĂŻn sent equivalents.