Zola Macros

2023-07-12

link

Zola is a fast static site generator in a single binary with everything built-in ¹ ². It uses the Tera template engine, which is similar to Jinja2, Django templates, Liquid, and Twig³.

Generic Macros

Macros are a way to reuse common parts of templates. They are similar to functions in programming languages. You can define macros in a separate file and import them in your templates. Macros can take arguments and return some HTML ref³.

Here is an example of a macro that creates a simple card component³:

Using the site structure:

content/
templates/
 - page.html
 - macros.html

{% macro card(title, text, image) %}
<div class="card">
{% if image %}
<img src="{{ image }}" alt="{{ title }}">
{% endif %}
<div class="card-content">
<h3>{{ title }}</h3>
<p>{{ text }}</p>
</div>
</div>
{% endmacro card %}

You can save this macro in a file called macros.html and import it in your template like this:

{% import "macros-gallery.html" as macros %}

{{ macros::card(title="Zola", text="A fast static site generator", image="zola.png") }}

This will render a card with the title, text and image you provided.

You can learn more about macros and other features of Zola from its documentation³.

Macros can't really provide return values for other templates but they can be embedded in specific cases.

Image Resizing and Content Colocation

You can resize images in Zola using the built-in function resize_image, which is available in template code as well as in shortcodes. The function takes the following arguments:

path: The path to the source image relative to the content directory.
width and height: The dimensions in pixels of the resized image. Usage depends on the op argument.
op (optional): Resize operation. This can be one of: "scale", "fit_width", "fit_height", "fit", or "fill". The default is "fill".
format (optional): Encoding format of the resized image. May be one of: "auto", "jpg", "png", or "webp". The default is "auto".
quality (optional): JPEG or WebP quality of the resized image, in percent. Only used when encoding JPEGs or WebPs; for JPEG default value is 75, for WebP default is lossless.

The function returns an object with the following schema:

url: The final URL for that asset
static_path: The path to the static asset generated
width: New image width
height: New image height
orig_width: Original image width
orig_height: Original image height

For example, to resize an image called logo.png to 200 pixels wide and 100 pixels high, you can use this code in your template:

content/
  _index.md
  gallery/
    _index.md
    logo/
      index.md
      logo.png
 
templates/
 - imagedisplay.html

Resizing

{% set resized = resize_image(path="logo.png", width=200, height=100) %}
<img src="{{ resized.url }}" alt="Logo" width="{{ resized.width }}" height="{{ resized.height }}">

You can learn more about the resize operations and how Zola performs image processing from its documentation⁴.

As for storing images next to the content, Zola supports assets co-location. This means that you can place any static files (such as images, CSS, JavaScript, etc.) in the same directory as your content files and they will be copied to the output directory with the same structure⁵. For example, if you have a page called blog/my-post.md and an image called blog/my-image.jpg, they will be copied to public/blog/my-post/index.html and public/blog/my-image.jpg, respectively.

You can access the co-located assets using the page.permalink variable, which is the full URL of a page without a trailing slash⁵. For example, to display an image called my-image.jpg that is co-located with a page called my-post.md, you can use this code in your template:

Direct use of an image

<img src='{{ page.permalink ~ "my-image.jpg" }}' alt="My image">

You can learn more about assets co-location and other features of Zola from its documentation⁵.

Zola Macros

Generic Macros

Image Resizing and Content Colocation

Resizing

Direct use of an image

Footnotes