Linkita

Components

2026-09-13T00:00:00+00:00

The Linkita theme providers multiple components.

Never heard of components? See Zola documentation for more information.

Mermaid component

To use Mermaid in your page, you have to set extra.mermaid = true in the frontmatter of page.

+++
title = "Your page title"

[extra]
mermaid = true
+++

Then you can use the <mermaid> component like:

{% <mermaid> %}

graph TD;
A-->B;
A-->C;
B-->D;
C-->D;

{% </mermaid> %}

This will be rendered as:

  

graph TD;
A-->B;
A-->C;
B-->D;
C-->D;

In addition, you can use code block inside <mermaid> components and the code block will be ignored.

The code block prevents formatter from breaking mermaid's formatting.

{% <mermaid> -%}

```mermaid
sequenceDiagram
    participant Alice
    participant Bob
    Alice->>John: Hello John, how are you?
    loop Healthcheck
        John->>John: Fight against hypochondria
    end
    Note right of John: Rational thoughts <br/>prevail!
    John-->>Alice: Great!
    John->>Bob: How about you?
    Bob-->>John: Jolly good!
```

{%- </mermaid> %}

This will be rendered as:

  
sequenceDiagram
    participant Alice
    participant Bob
    Alice->>John: Hello John, how are you?
    loop Healthcheck
        John->>John: Fight against hypochondria
    end
    Note right of John: Rational thoughts 
prevail!
    John-->>Alice: Great!
    John->>Bob: How about you?
    Bob-->>John: Jolly good!

Admonition

The <admonition> component displays a banner to help you put notice in your page.

You can use the component like:

{% <admonition type="tip" title="tip"> %}
The `tip` admonition.
{% </admonition> %}

The admonition component has 12 different types:

note

note

The note admonition.

abstract

abstract

The abstract admonition.

info

info

The info admonition.

tip

tip

The tip admonition.

success

success

The success admonition.

question

question

The question admonition.

warning

warning

The warning admonition.

failure

failure

The failure admonition.

danger

danger

The danger admonition.

bug

bug

The bug admonition.

example

example

The example admonition.

quote

quote

The quote admonition.

Gallery

The <gallery /> component is very simple html-only clickable picture gallery that displays all images from the page assets.

It's from Zola documentation

{{ <gallery /> }}

Projects

The <projects /> component allows you to make a page for your projects.

Create a content/pages/projects/index.md file:

+++
title = "My Projects"
description = ""
path = "projects"
+++

{{ <projects path="data.toml" format="toml" /> }}

Create a content/pages/projects/data.toml file:

[[project]]
name = "lorem"
desc = "Lorem ipsum dolor sit."
tags = ["lorem", "ipsum"]
links = [
    { name = "homepage", url = "https://example.com" },
    { name = "source", url = "https://example.com" },
]

This will be displayed as:

lorem

Lorem ipsum dolor sit.

#lorem #ipsum

homepage source

Switch to Zola 0.23.4

2026-09-12T00:00:00+00:00

Zola v0.23 replaced its template engine, Tera, with a new major version (Tera v2). The Zola project itself calls it

probably the most breaking version of Zola that will happen

and Linkita's templates had to be rewritten to follow it. This page walks you through moving a Linkita site from Zola v0.22.1 to Zola v0.23.4.

Repository move

Linkita was simultaneously moved from Codeberg to GitHub. If you are still using the Codeberg repository, you need to switch to the GitHub repository first. For submodule users, here are the instructions:

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

Who needs this guide

This guide is for you if your site currently uses Linkita on the tera1 branch (or on linkita / v4) with Zola v0.22.1 or older.

If you don't want to upgrade Zola yet, you don't have to do anything – the tera1 branch will keep working with old Zola versions and isn't going away.

Step 1: Upgrade Zola to v0.23.4

Install Zola v0.23.4 or newer. Check your installed version with:

zola --version

Zola v0.23 is a big jump. Skim the Zola v0.23.0 changelog entry if your site has custom templates beyond Linkita's own – the rest of this guide only covers what changed on Linkita's side.

Step 2: Switch to the `main` branch

Linkita's main branch now targets Zola v0.23.0+. The tera1 branch stays on the old template engine for Zola v0.22.1 and older.

If you installed Linkita as a git submodule:

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

Step 3: Update your `zola.toml` / `config.toml`

Go through each of the following. None of these are enforced by Zola – leftover old keys won't break your build, but they'll silently stop doing anything, so it's worth cleaning them up.

Menu and social links: `$BASE_URL` → `@base`

$BASE_URL in extra.menus, profile social URLs, and extra.footer.license_url is now written @base:

# Before
[extra.menus]
menu_name = [
  { url = "$BASE_URL/blog/", name = "Archive" },
]

# After
[extra.menus]
menu_name = [
  { url = "@base/blog/", name = "Archive" },
]

The same rename applies to a profile's social entries and to extra.footer.license_url. You can also use Zola's internal links (@/...) instead of @base if you prefer.

There's also a new @lang prefix for menu/social URLs that resolves a path within a specific language, if you need that.

Note this does not apply to extra.footer.copyright – that string still uses $BASE_URL, $YEAR, and $LICENSE_URL as before:

[extra.footer]
copyright = "&copy;&nbsp;$YEAR Your Name &vert; [CC BY-SA 4.0]($LICENSE_URL)"

Profiles: Open Graph settings simplified

The [extra.profiles.<user>.open_graph] sub-table is gone. image and image_alt moved up a level and were renamed, fediverse_creator moved up a level too, and the Facebook-specific fields (first_name, last_name, username, gender, fb_app_id, fb_admins) and the per-language Open Graph translation section were removed entirely:

# Before
[extra.profiles.your_username.open_graph]
image = "cover.png"
image_alt = "A description"
fediverse_creator = { handle = "me", domain = "mastodon.social" }

# After
[extra.profiles.your_username]
# ...avatar_url, name, bio, social, etc. as before, plus:
og_image = "cover.png"
og_image_alt = "A description"
fediverse_creator = { handle = "me", domain = "mastodon.social" }

If you relied on first_name / last_name / gender / fb_app_id / fb_admins, or on a per-language open_graph.languages.<lang>.image_alt override, there's no direct replacement – those Open Graph fields are no longer emitted by the theme.

Language options: `locale` removed, date formatting changed

Zola's date filter no longer takes a locale argument, so the extra.languages.<lang>.locale variable (e.g. locale = "fr_FR") has been removed. Date formatting moved from the chrono crate to jiff, so date_format strings are now interpreted using jiff's strftime reference rather than chrono's.

# Before
[extra.languages.fr]
locale = "fr_FR"
date_format = "%x"

# After
[extra.languages.fr]
date_format = "%F"
num_format = "fr"

The practical effect: if you were relying on locale to print translated month/weekday names (via tokens like %B or %A), that no longer happens automatically. Check your date_format tokens against the jiff docs – you may want to switch to a numeric-only format, or accept that month/day names will render in whatever jiff produces by default for that token. num_format (for number formatting, unrelated to dates) is unchanged and still per language.

`disable_javascript` removed

The extra.disable_javascript config variable, which let you suppress the theme's JS and re-implement it yourself via injects, has been removed.

Documentation links

If you link to Linkita's own documentation anywhere, note the shortcode demo moved from /shortcodes/ to /components/ (e.g. the projects feature is now documented at https://salif.github.io/linkita/components/#projects).

The cover image docs were clarified to note extra.cover.image accepts either a page asset filename or a get_url-compatible path – this already worked before, just wasn't spelled out.

Step 4: Update your content – shortcodes are now components

This is the change most likely to affect your existing posts.

Zola v0.23 removed shortcodes completely. There is no more templates/shortcodes/ directory, and the old function-call style of invoking a shortcode in Markdown content (with or without a body) is gone – both forms now fail the build with an "unknown function" / "unknown tag" error. Instead, your .md files are templated with Tera directly, the same as .html templates, and you call Linkita's built-in components using Tera v2's new call syntax.

A component with a body is called like this – note the closing percent-brace and opening percent-brace wrap the angle-bracket tags, not double curly braces:

{% <component_name arg="value"> %}
body content
{% </component_name> %}

A component with no body (self-closing) uses double curly braces instead:

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

Admonition

# Before
{% admonition(type="note", title="A note") %}
This is a **note** body.
{% end %}

# After
{% <admonition type="note" title="A note"> %}
This is a **note** body.
{% </admonition> %}

Gallery

Gallery now needs page and config passed in explicitly (Tera v2 components don't get implicit access to the page/config like old shortcodes did – you pass them by name, and since the variable names already match the parameter names, you can just write page config):

# Before
{{ gallery() }}

# After
{{<gallery page config alt="" />}}

Mermaid

# Before
{% mermaid() %}
```mermaid
graph TD;
A-->B;
```
{% end %}

# After
{% <mermaid> -%}
```mermaid
graph TD;
A-->B;
```
{%- </mermaid> %}

Use the whitespace-trim dashes shown above (right after the opening percent-brace and right before the closing one) – without them, the leading blank line before the fenced block isn't stripped and the diagram renders with the ```mermaid fence markers still visible instead of being cleaned up by the component.

Projects

Projects also now needs page and config passed explicitly:

# Before
{{ projects(path="data.toml", format="toml") }}

# After
{{<projects path="data.toml" format="toml" page config />}}

If you write about Tera syntax in your own posts

Since .md files are now templated by Tera before Markdown is parsed, literal Tera tags inside a fenced code block – like the examples above – will actually get executed rather than displayed, even inside triple-backtick fences. Wrap any such example in a raw block, to show it literally instead.

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

Step 5: Custom language files

If you added a custom static/i18n/<lang>.json file, synchronize your changes with the theme's default language file.

Step 6 (advanced): Custom template overrides or injects

Skip this section unless you've overridden one of Linkita's own templates, or you call its internal macros directly from your own templates or injects.

Tera v1 macros are gone in Tera v2, replaced by components, which are called globally by name – no more {% import %} or self:: namespacing.

Other Tera v2 syntax changes visible throughout the templates, in case your own overrides use them:

trim_start_matches(pat=...) / trim_end_matches(pat=...) are now trim_start(pat=...) / trim_end(pat=...).
linebreaksbr is now newlines_to_br.
default(value=x) needs boolean=true added (default(value=x, boolean=true)) to treat empty strings/false as "use the default" – without it, only a truly undefined/null value triggers the default.
Optional chaining (?. / ?[...]) is available and used throughout for safely reading config values that might not be set.
Global context (page, config, lang, etc.) is no longer implicitly available inside a component the way it was inside a macro – components declare and receive it explicitly, which is why you'll see page: map, config: map parameters throughout the new templates.
The custom templates/sitemap.xml and templates/split_sitemap_index.xml templates were removed from the theme. If you had overridden either of these yourself, check whether you still need to.

For the full picture of what changed in Tera itself, see the Tera v1 → v2 migration guide.

Step 7: Rebuild and check

zola build

Then review, especially:

Menu items and social icons resolve to the right URLs (the @base change).
Your profile's Open Graph image/description and Fediverse verification link tag are present in the page <head>.
Non-English date formatting still looks right – this is the one most likely to have silently changed (no more locale-translated month/day names).
Any admonitions, galleries, Mermaid diagrams, or a projects page render correctly.

Getting help

If something doesn't match what's described here, check the README and CHANGELOG on the main branch, or start a discussion.

Extra frontmatter

2025-04-11T00:00:00+00:00

[extra]

# Enable comments.
comment = true

# Enable KaTeX support.
math = true

# Enable Mermaid support.
mermaid = true

# Default value: config.extra.page_summary_on_paginator
page_summary_on_paginator = true

# Default value:
#  config.extra.page_info or config.extra.page_info_on_paginator
page_info = []

# Default value: config.extra.toc
toc = true

# For the archive.html template.
section = "_index.md"

# For the archive.html template.
date_attribute = "date"

# For the archive.html template.
year_attribute = "year"

# Set only if different from canonical page URL.
# Default value: current_url
og_url = ""

[extra.cover]

# Path to the cover image.
image = ""
# A description of the cover image.
alt = ""

# Width of the cover image in pixels.
# Not required.
width =
# Height of the cover image in pixels.
# Not required.
height =

Math Typesetting

2024-11-08T00:00:00+00:00

Linkita theme supports $\LaTeX$ mathematical formulas using KaTeX.

Markdown Syntax Guide

2023-10-20T00:00:00+00:00

This article offers a sample of basic Markdown syntax that can be used in Zola content files, also it shows whether basic HTML elements are decorated with CSS in a Linkita theme.

Placeholder Text

2023-10-20T00:00:00+00:00

Lorem est tota propiore conpellat pectoribus de pectora summo.…

Linkita

Components

Mermaid component

Admonition

Gallery

Projects

lorem

Switch to Zola 0.23.4

Repository move

Who needs this guide

Step 1: Upgrade Zola to v0.23.4

Step 2: Switch to the main branch

Step 3: Update your zola.toml / config.toml

Menu and social links: $BASE_URL → @base

Profiles: Open Graph settings simplified

Language options: locale removed, date formatting changed

disable_javascript removed

Documentation links

Step 4: Update your content – shortcodes are now components

Admonition

Gallery

Mermaid

Projects

If you write about Tera syntax in your own posts

Step 5: Custom language files

Step 6 (advanced): Custom template overrides or injects

Step 7: Rebuild and check

Getting help

Extra frontmatter

Math Typesetting

Markdown Syntax Guide

Placeholder Text

Step 2: Switch to the `main` branch

Step 3: Update your `zola.toml` / `config.toml`

Menu and social links: `$BASE_URL` → `@base`

Language options: `locale` removed, date formatting changed

`disable_javascript` removed