Actualiza tu sitio tabi a Zola 0.23

Zola 0.23.0 ha cambiado muchas cosas, sobre todo por la actualización a Tera 2.

Como esto obliga a los usuarios a hacer cambios, he aprovechado para retirar ajustes que solo existían por retrocompatibilidad. Este documento pretende facilitar la transición.

tabi requiere Zola 0.23.6 o superior. Comprueba la versión que usas en local, en CI y en el despliegue:

zola --version

Si necesitas quedarte en una versión de Zola anterior a la 0.23.0, fija tabi en v4.2.0, la última versión compatible.

Si ya tienes 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

Como submódulo:

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 repositorio padre guarda el commit del submódulo, no el nombre de la etiqueta. Para un clon nuevo:

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

Índice

Elimina los ajustes retirados

  • footnote_backlinks: usa [markdown].bottom_footnotes = true.
  • add_src_to_code_block: usa bloques de código con nombre y code_block_name_links.
  • [extra].index_format: muévelo a [search] y a la tabla de búsqueda de cada idioma activado.
  • translate_copyright y translated_copyright: usa copyright_translations.

Actualiza los formatos de fecha

Si has configurado long_date_format, short_date_format, archive_date_format o date_formats, reescribe cada valor usando patrones UTS-35. Las directivas % de strftime fallan cuando tabi aplica la configuración regional del idioma.

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

# Después
long_date_format = "dd MMMM y"

Las sustituciones más comunes son %-d → d, %d → dd, %b → MMM, %B → MMMM y %Y → y. Escribe el texto literal entre apóstrofos: d 'de' MMMM 'de' y.

Localiza lo que hay que cambiar

Busca llamadas a shortcodes en línea:

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

Busca llamadas a shortcodes de bloque:

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

Cada resultado indica un archivo, un número de línea y la llamada. Aparecerán dos tipos:

  • Shortcodes como admonition, toc o dual_theme_image. Conviértelos a la sintaxis de componentes, como se explica más abajo.
  • Funciones integradas como get_url, resize_image o get_taxonomy_url. Estas siguen funcionando en la 0.23. No las toques.

Si envolviste ejemplos en {% raw %}, esos resultados son texto literal. Tampoco los toques.

Lista tus shortcodes y macros propios:

ls templates/shortcodes templates/macros

Todo lo que aparezca es tuyo, no de tabi, y hay que migrarlo a templates/components/.

Revisa la configuración en busca de ajustes retirados:

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

Actualiza el resaltado de sintaxis

Mueve los ajustes de resaltado de [markdown] a [markdown.highlighting]:

[markdown]
smart_punctuation = true

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

Para usar temas distintos:

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

tabi requiere style = "class". Zola genera giallo.css, o bien giallo-light.css y giallo-dark.css.

Configura la búsqueda multilingüe

La tabla [search] de la raíz configura el idioma por defecto. Cada idioma adicional con build_search_index = true necesita su propia tabla:

build_search_index = true

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

[languages.es]
title = "Mi sitio"
build_search_index = true

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

Convierte los shortcodes en componentes

Las llamadas en línea pierden los paréntesis y las comas:

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

Las llamadas de bloque usan etiquetas de cierre con nombre:

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

Envuelve entre llaves las expresiones, los booleanos, los números, los arrays y los mapas. Por defecto, los parámetros de los componentes son explícitos. Prefija con @ los parámetros de contexto ambiental en la definición del componente para que Tera los resuelva desde el llamador:

{% 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 tus shortcodes propios

Mueve las plantillas de tu sitio de templates/shortcodes/ a templates/components/ y define un componente. Este ejemplo está adaptado de un sitio que usa 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} />}}

Usa parámetros normales para las entradas del componente y parámetros implícitos para valores ambientales como lang, config o page. Un valor implícito todavía puede sobrescribirse explícitamente en el lugar de la llamada.

Protege los ejemplos literales

El markdown se procesa como plantilla antes de renderizar los bloques de código. Envuelve los ejemplos literales entre {% raw %} y {% endraw %} en el archivo fuente.

Los identificadores de encabezado personalizados no necesitan bloques raw:

## Comprobaciones de despliegue {#comprobaciones-de-despliegue}

Usa skip_content_templating solo cuando el archivo completo deba saltarse el procesado de plantillas.

Revisa tus plantillas personalizadas

Las plantillas propias que sobrescriben las del tema, en templates/, no se actualizan junto al tema.

AntesAhora
macros e {% import %}componentes
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 para arraysis array
get_taxonomy_url(..., name=term)get_taxonomy_url(..., term=term)
{% include "x" ignore missing %}incluye un archivo por defecto que exista

El acceso a valores indefinidos es más estricto. Usa encadenamiento opcional, como page?.extra?.setting, y comprueba los valores nulos explícitos antes de aplicarles filtros. default(value=...) gestiona los valores indefinidos, no los nulos.

get_page y get_section reciben una ruta canónica y lang. Los argumentos de los componentes usan literales de cadena o expresiones entre llaves; page es la forma abreviada de page={page}.

Consulta la guía de migración de Tera para ver todos los cambios del lenguaje.

Diferencias esperadas en la salida

  • Notas al pie: etiquetas entre corchetes y enlaces absolutos con fragmentos #fn-* y #fr-*.
  • Resaltado: clases de tokens numeradas z-*, o bien z-l-*/z-d-*.
  • Espacios en blanco: hay diferencias alrededor de la salida de los componentes; revisa el contenido en línea y los anidamientos.
  • Orden de los idiomas: puede cambiar el orden del selector de idioma y de los hreflang; los destinos no deberían cambiar.
  • XML: el escapado puede variar, aunque los valores descodificados sigan siendo equivalentes.