Custom components

Diagram component

Mermaid diagrams

Mermaid is a a diagramming and charting tool that uses text and code to generate diagrams. It supports flowcharts, sequence diagrams, Gantt charts, and more.

To include a Mermaid diagram in your post, there are two steps:

1. Set mermaid = true in the [extra] section of the front matter of your page, section or config.toml. This will load the JavaScript needed to render the diagrams.

2. Use the mermaid component to define your diagram in your posts. For example:

{% <mermaid> %}
classDiagram
    class CognitiveDistortions {
        +AllOrNothingThinking()
        +Overgeneralization()
        +MentalFilter()
        +JumpingToConclusions()
    }
    class AllOrNothingThinking {
        +SeeInExtremes()
    }
    class Overgeneralization {
        +GeneralizeFromSingle()
    }
    class MentalFilter {
        +FocusOnNegative()
    }
    class JumpingToConclusions {
        +MakeAssumptions()
    }
    CognitiveDistortions *-- AllOrNothingThinking
    CognitiveDistortions *-- Overgeneralization
    CognitiveDistortions *-- MentalFilter
    CognitiveDistortions *-- JumpingToConclusions
{% </mermaid> %}

The diagram will be rendered as follows:

classDiagram
    class CognitiveDistortions {
        +AllOrNothingThinking()
        +Overgeneralization()
        +MentalFilter()
        +JumpingToConclusions()
    }
    class AllOrNothingThinking {
        +SeeInExtremes()
    }
    class Overgeneralization {
        +GeneralizeFromSingle()
    }
    class MentalFilter {
        +FocusOnNegative()
    }
    class JumpingToConclusions {
        +MakeAssumptions()
    }
    CognitiveDistortions *-- AllOrNothingThinking
    CognitiveDistortions *-- Overgeneralization
    CognitiveDistortions *-- MentalFilter
    CognitiveDistortions *-- JumpingToConclusions

The Mermaid component supports two parameters:

• invertible: If set to true (default), the diagram will be inverted in dark mode, just like invertible images.
• full_width: Allows the diagram to take up the width of the header. See full-width image.

Usage

{% <mermaid invertible={true} full_width={false}> %}

Your diagram goes here.

`invertible` or `full_width` can be omitted if default values are used.

{% </mermaid> %}

Image components

All image components support absolute paths, relative paths, and remote sources in the src parameter.

All image components have these optional parameters:

• raw_path. Defaults to false. If set to true, the src parameter will be used as is. Useful for colocated assets with a custom slug (see Zola issue #2598).
• inline. Defaults to false. If set to true, the image will be displayed inline with the text.
• full_width. Defaults to false (see below)
• lazy_loading. Defaults to true.

Dual theme images

Useful if you want to use a different image for the light and dark themes:

Usage

{{< dual_theme_image light_src="img/paris_day.webp" dark_src="img/paris_night.webp" alt="The Eiffel tower" />}}

Invertible image

Good for graphs, line drawings, diagrams… Inverts the colours of the image. The source image will be used for the light theme.

Usage

{{< invertible_image src="img/graph.webp" alt="Invertible graph" />}}

Dimmable image

Images with too much brightness or contrast can be jarring against a dark background. Here’s an example of a photograph that dims when the dark theme is active.

Usage

{{< dimmable_image src="img/desert_by_oskerwyld.webp" alt="Photograph of a desert, heavenly sky" />}}

Swap image on hover

Provides an interaction where the image displayed changes as the user hovers over it. Useful for before-after comparisons, for example.

Usage

{{< image_hover default_src="img/before.webp" hovered_src="img/after.webp" default_alt="Edited picture" hovered_alt="Original shot" />}}

Interactive image toggle

Display an image and switch to a different one on click. Ideal for highlighting differences or drawing attention to details.

Usage

{{< image_toggler default_src="img/mojave_day.webp" toggled_src="img/mojave_night.webp" default_alt="Mojave during the day" toggled_alt="Mojave at night" />}}

Full-width image

The image will expand to match the width of the header, which is usually wider than the article text (except on mobile/small windows).

All other image components can be made into full-width by setting the optional parameter full_width to true.

Usage

{{< full_width_image src="img/amsterdam_by_oskerwyld.webp" alt="Photograph of a canal in Amsterdam" />}}

Engagement components

iine

This component allows you to add extra iine.to buttons to your posts, like this:

Usage

{{< iine icon="heart" slug="/post/my-post-slug/like" label="Like this post" />}}

The component takes the following optional parameters:

• icon: The icon to display. Can be heart, thumbs_up, upvote, or any emoji.
• slug: A unique identifier. Defaults to the current page’s path. Useful if you want more than one button on the same page.
• label: The accessibility label for the button. Defaults to “Like this post”.

Code components

Show source or path

You can display a path or URL for a code block using Zola’s native syntax:

```rust,name=src/main.rs
fn main() {
    println!("Hello, world!");
}
```

This renders:

fn main() {
    println!("Hello, world!");
}

If you set the name to a URL (i.e. it starts with http or https), you can turn it into a clickable link. This is particularly useful when used in conjunction with the remote text component.

__pycache__/
*coverage*
.vscode/
dist/

Text components

Aside (side/margin note)

Add supplementary content in the margins on wide screens, or as distinct blocks on mobile.

The component accepts two parameters:

• position: Set to "right" to place in right margin (defaults to left)
• Content can be provided via text parameter or between component tags

Usage

Using the text parameter:

{{< aside text="*Sidenote* comes from Latin *nota* ('mark') + Old English *síde* ('side')." />}}

Using the content body and setting the position to right:

{% <aside position="right"> %}
A longer note that
can span multiple lines.

_Markdown_ is supported.
{% </aside> %}

Remote text

Embed text from a remote URL or a local file. To display the path or URL on the code block, see the show source or path component.

The component accepts three parameters:

• src: The source URL or file path (required)
• start: First line to display (optional, starts at 1)
• end: The ending line number (optional, defaults to 0, meaning the last line)

Important:

• Remote VS local files: If src starts with “http”, it will be treated as a remote file. Otherwise, it assumes a local file path.
• Files access: As it uses Zola’s load_data, local files must be inside the Zola directory—see File searching logic. The component supports both relative and absolute paths.
• Code block formatting: To display the text as a code block, you must manually add the Markdown code fences (backticks) and, optionally, specify the programming language for syntax highlighting.

Usage

Embedding a remote Python script within a code block with syntax highlighting:

```python
{{< remote_text src="https://example.com/script.py" />}}
```

Displaying text from a local file:

{{< remote_text src="path/to/file.txt" />}}

Display lines 3 to 7 (both inclusive) of a local file:

{{< remote_text src="path/to/file.txt" start={3} end={7} />}}

Admonitions

Bring attention to information with these admonition/alert components. They come in five types: note, tip, info, warning, and danger.

You can change the title and icon of the admonition. Both parameters take a string and default to the type of admonition. icon can be any of the available admonition types.

Usage

You can use admonitions in two ways:

1. Inline with parameters:

{{< admonition type="danger" icon="tip" title="An important tip" text="Stay hydrated~" />}}

2. With a content body:

{% <admonition type="danger" icon="tip" title="An important tip"> %}
Stay hydrated~

This method is particularly useful for longer content or multiple paragraphs.
{% </admonition> %}

Both methods support the same parameters (type, icon, and title), with the content either passed as the text parameter or as the body between tags.

Multilingual quotes

This component allows you to display both the translated and original text for a quote. The quotation marks will be added automatically:

Usage

{{< multilingual_quote original="Qué sosiego, ir por la vida en silencio, saludando sólo a los amigos." translated="What tranquillity, to go through life in silence, greeting only friends." author="Francisco Umbral" />}}

References with hanging indent

This component formats a reference section with a hanging indent like so:

Usage

{% <references> %}

Your references go here.

Each in a new line. Markdown (links, italics…) will be rendered.

{% </references> %}

Spoiler

This component allows you to blur text until the user clicks on it. Like this: Goldfish have a memory span of a few

As you can see, Markdown is rendered. You can even add newlines with <br>.

This component has the optional flag fixed_blur to blur a fixed placeholder (“SPOILER”), instead of blurring the actual contents. Like this: it is

Usage

{{< spoiler text="text to hide" fixed_blur={false} />}}

Containers

Wide container

Use this component if you want to have a wider table, paragraph, code block… On desktop, it will take up the width of the header. It will have no effect on mobile, except for tables, which will get a horizontal scroll.

Usage

{% <wide_container> %}

Place your code block, paragraph, table… here.

Markdown will of course be rendered.

{% </wide_container> %}

Force text direction

Force the text direction of a content block. Overrides both the global force_codeblock_ltr setting and the document’s overall direction.

Accepts the parameter direction: the desired text direction. This can be either “ltr” (left-to-right) or “rtl” (right-to-left). Defaults to “ltr”.

def مرحبا_بالعالم():
    print("مرحبا بالعالم!")

Usage

In a LTR page we can force a code block to be RTL (as shown above) like so:

{% <force_text_direction direction="rtl"> %}

```python
def مرحبا_بالعالم():
    print("مرحبا بالعالم!")
```

{% </force_text_direction> %}