Преминаване към Зола 0.23.3

2026-08-165 минСалиф

Зола 0.23 замени своя шаблонен механизъм, Тера, с нова основна версия (Тера 2). Самият проект Зола го определя като

вероятно най-несъвместимата с предишни версии промяна в Зола, която някога ще се случи

и шаблоните на Линкита трябваше да бъдат пренаписани, за да го следват. Тази страница ви превежда през преместването на сайт с Линкита от Зола 0.22.1 към Зола 0.23.3.

Преместване на хранилището

Линкита едновременно с това беше преместена от Codeberg в GitHub. Ако все още използвате хранилището в Codeberg, първо трябва да преминете към хранилището в GitHub. За потребители на git submodule, ето инструкциите:

git submodule init
git config -f .gitmodules submodule."themes/linkita".url https://github.com/salif/linkita.git
git config -f .gitmodules submodule."themes/linkita".branch tera1
git submodule sync
git submodule update
git add .gitmodules

За кого е това ръководство

Това ръководство е за вас, ако вашият сайт в момента използва Линкита от клона tera1 (или от linkita / v4) със Зола 0.22.1 или по-стара.

Ако все още не искате да надграждате Зола, не е нужно да правите нищо – клонът tera1 ще продължи да работи със стари версии на Зола и няма да бъде премахнат.

Стъпка 1: Надграждане на Зола до 0.23.3

Инсталирайте Зола 0.23.3 или по-нова. Проверете инсталираната си версия с:

zola --version

Зола 0.23 е голям скок. Прегледайте списъка с промени за Зола 0.23.0, ако сайтът ви има персонализирани шаблони извън тези на Линкита – останалата част от това ръководство покрива само промените от страна на Линкита.

Стъпка 2: Преминаване към клона `main`

Клонът main на Линкита вече е насочен към Зола 0.23.3+. Клонът tera1 остава на стария шаблонен механизъм за Зола 0.22.1 и по-стари версии.

Ако сте инсталирали Линкита като git submodule:

git submodule set-branch --branch main themes/linkita
git submodule update --remote themes/linkita

Стъпка 3: Актуализиране на вашия `zola.toml` / `config.toml`

Прегледайте всяка от следните точки. Нито една от тях не се налага задължително от Зола – останалите стари ключове няма да счупят компилацията, но просто тихо ще спрат да работят, така че си струва да ги почистите.

Връзки в менюто и социални мрежи: `$BASE_URL` → `@base`

$BASE_URL в extra.menus, URL адресите в профила social и extra.footer.license_url вече се изписват като @base:

# Преди
[extra.menus]
menu_name = [
  { url = "$BASE_URL/blog/", name = "Архив" },
]

# След
[extra.menus]
menu_name = [
  { url = "@base/blog/", name = "Архив" },
]

Същото преименуване се прилага за записите social на профила и за extra.footer.license_url. Можете също така да използвате вътрешните връзки на Зола (@/...) вместо @base, ако предпочитате.

Има и нов префикс @lang за URL адреси в менюта/социални мрежи, който разрешава път в рамките на определен език, ако ви е необходимо.

Имайте предвид, че това не се прилага за extra.footer.copyright – този низ все още използва $BASE_URL, $YEAR и $LICENSE_URL, както и преди:

[extra.footer]
copyright = "&copy; $YEAR Вашето Име &vert; [CC BY-SA 4.0]($LICENSE_URL)"

Профили: Опростени настройки на Open Graph

Подтаблицата [extra.profiles.<user>.open_graph] е премахната. image и image_alt бяха преместени едно ниво нагоре и преименувани, fediverse_creator също беше преместен едно ниво нагоре, а специфичните за Facebook полета (first_name, last_name, username, gender, fb_app_id, fb_admins) и секцията за превод на Open Graph за отделни езици бяха премахнати напълно:

# Преди
[extra.profiles.your_username.open_graph]
image = "cover.png"
image_alt = "Описание"
fediverse_creator = { handle = "me", domain = "mastodon.social" }

# След
[extra.profiles.your_username]
# ...avatar_url, name, bio, social и т.н. както преди, плюс:
og_image = "cover.png"
og_image_alt = "Описание"
fediverse_creator = { handle = "me", domain = "mastodon.social" }

Ако сте разчитали на first_name / last_name / gender / fb_app_id / fb_admins или на специфично за език предефиниране open_graph.languages.<lang>.image_alt, няма директен заместител – тези Open Graph полета вече не се генерират от темата.

Езикови опции: `locale` е премахнат, форматирането на дати е променено

Филтърът date на Зола вече не приема аргумент locale, така че променливата extra.languages.<lang>.locale (напр. locale = "fr_FR") е премахната. Форматирането на дати премина от библиотеката chrono към jiff, така че низовете date_format вече се интерпретират чрез справката за strftime на jiff, а не според chrono.

# Преди
[extra.languages.fr]
locale = "fr_FR"
date_format = "%x"

# След
[extra.languages.fr]
date_format = "%F"
num_format = "fr"

Практическият ефект: ако сте разчитали на locale за отпечатване на преведени имена на месеци/дни от седмицата (чрез маркери като %B или %A), това вече не става автоматично. Проверете вашите date_format маркери спрямо документацията на jiff – може да поискате да преминете към изцяло цифров формат или да приемете, че имената на месеците/дните ще се извеждат според това, което jiff генерира по подразбиране. num_format (за форматиране на числа, несвързано с дати) е непроменено и все още е специфично за всеки език.

`disable_javascript` е премахнат

Конфигурационната променлива extra.disable_javascript, която позволяваше спиране на JS на темата и повторното му внедряване чрез инжекции (injects), е премахната.

Връзки към документацията

Ако поставяте връзки към документацията на Линкита някъде, имайте предвид, че демонстрацията на кратки кодове се премести от /shortcodes/ в /components/ (напр. функцията за проекти вече е документирана на https://salif.github.io/linkita/components/#projects).

Документацията за изображението на корицата беше пояснена, за да се отбележи, че extra.cover.image приема или име на файл от ресурсите на страницата, или съвместим с get_url път – това работеше и преди, но просто не беше изрично уточнено.

Стъпка 4: Актуализиране на съдържанието – кратките кодове вече са компоненти

Това е промяната, която най-вероятно ще засегне съществуващите ви публикации.

Зола 0.23 премахна напълно кратките кодове (shortcodes). Вече няма директория templates/shortcodes/, а старият стил на извикване като функция в Маркдаун съдържание (със или без тяло) изчезна – и двете форми вече водят до неуспешно компилиране с грешка "unknown function" / "unknown tag". Вместо това вашите .md файлове се обработват директно с Тера, точно както .html шаблоните, и извиквате вградените компоненти на Линкита чрез новия синтаксис за извикване в Тера 2.

Компонент с тяло се извиква така – забележете, че знакът за процент и фигурна скоба обхващат ъгловите скоби, а не двойни фигурни скоби:

{% <component_name arg="value"> %}
съдържание на тялото
{% </component_name> %}

Компонент без тяло (самозатварящ се) използва двойни фигурни скоби:

{{<component_name arg="value" />}}

Предупреждения (Admonition)

# Преди
{% admonition(type="note", title="Бележка") %}
Това е тялото на **бележката**.
{% end %}

# След
{% <admonition type="note" title="Бележка"> %}
Това е тялото на **бележката**.
{% </admonition> %}

Галерия (Gallery)

Галерията вече изисква page и config да се подават изрично (компонентите в Тера 2 нямат неявен достъп до страницата/конфигурацията, както имаха старите кратки кодове – подавате ги по име, и тъй като имената на променливите вече съвпадат с имената на параметрите, можете просто да напишете page config):

# Преди
{{ gallery() }}

# След
{{<gallery page config alt="" />}}

Mermaid

# Преди
{% mermaid() %}
```mermaid
graph TD;
A-->B;
```
{% end %}

# След
{% <mermaid> -%}
```mermaid
graph TD;
A-->B;
```
{%- </mermaid> %}

Използвайте тиретата за премахване на празни пространства, показани по-горе (веднага след отварящата скоба за процент и точно преди затварящата) – без тях началният празен ред преди блока с код не се изчиства и диаграмата се рендерира с видими маркери ```mermaid, вместо да бъде изчистена от компонента.

Проекти (Projects)

Проектите също изискват page и config да се подават изрично:

# Преди
{{ projects(path="data.toml", format="toml") }}

# След
{{<projects path="data.toml" format="toml" page config />}}

Ако пишете за синтаксиса на Тера във вашите публикации

Тъй като .md файловете вече се обработват от Тера преди анализ на Маркдаун, буквалните тагове на Тера вътре в блоков код – като примерите по-горе – всъщност ще се изпълняват, вместо да се показват като текст, дори вътре в тройни апострофи. Обградете всеки такъв пример в raw блок, за да го покажете буквално.

{% raw %}
...
{% endraw %}

Стъпка 5: Персонализирани езикови файлове

Ако сте добавили персонализиран файл static/i18n/<lang>.json, синхронизирайте промените си с езиковия файл по подразбиране на темата.

Стъпка 6 (за напреднали): Персонализирани замени на шаблони или инжекции

Пропуснете този раздел, освен ако не сте заменили някой от шаблоните на Линкита или не извиквате неговите вътрешни макроси директно от собствените си шаблони или инжекции.

Макросите от Тера 1 са премахнати в Тера 2 и са заменени от компоненти, които се извикват глобално по име – няма повече {% import %} или именно пространство self::.

Други синтактични промени в Тера 2, видими в шаблоните, в случай че вашите замени ги използват:

trim_start_matches(pat=...) / trim_end_matches(pat=...) вече са trim_start(pat=...) / trim_end(pat=...).
linebreaksbr вече е newlines_to_br.
default(value=x) изисква добавяне на boolean=true (default(value=x, boolean=true)), за да третира празни низове/false като "използвай стойността по подразбиране" – без това само напълно недефинирана/null стойност задейства стойността по подразбиране.
Опционалното свързване (?. / ?[...]) е налично и се използва навсякъде за безопасно четене на конфигурационни стойности, които може да не са зададени.
Глобалният контекст (page, config, lang и т.н.) вече не е неявно достъпен вътре в даден компонент по начина, по който беше вътре в макрос – компонентите го декларират и приемат изрично, поради което ще виждате параметри page: map, config: map в новите шаблони.
Персонализираните шаблони templates/sitemap.xml и templates/split_sitemap_index.xml бяха премахнати от темата. Ако сте ги заменили сами, проверете дали все още се нуждаете от тях.

За пълна представа какво се е променило в самата Тера, вижте ръководството за миграция от Тера 1 към 2.

Стъпка 7: Повторно изграждане и проверка

zola build

След това прегледайте, особено:

Елементите на менюто и иконите на социалните мрежи да сочат към правилните URL адреси (промяната @base).
Open Graph изображението/описанието на вашия профил и етикетът за връзка за потвърждение във Fediverse да присъстват в <head> на страницата.
Форматирането на дати на неанглийски езици да изглежда правилно – това е промяната, която най-вероятно е настъпила тихо (няма повече локализирани преводи на имена на месеци/дни).
Всички предупреждения, галерии, диаграми Mermaid или страницата за проекти да се изобразяват коректно.

Помощ

Ако нещо не съответства на описаното тук, проверете README и CHANGELOG в клона main или започнете дискусия.