Build a Website with Zola

September 02, 2026

This is the tool I use currently for this website, and I like it as is pretty minimalist and fast.

You can check more about it in www.getzola.org, but still I will show you some cheats.

Installation

Depending on your Operative System, install Zola.

Linux

I prefer to install it via Flatpak:

flatpak install flathub org.getzola.zola

macOS

Available on Brew:

brew install zola

Windows

If for some reason you are still using ~~Winshit~~ Windows, is available in wget:

winget install getzola.zola

From now on, I will asume you are using Linux

CLI usage

If you installed via Flatpak, create an alias in your ~/.bashrc (bash) or ~/.zshrc (zsh):

alias zola="flatpak run org.getzola.zola"

Then reload your shell:

source ~/.zshrc

Now, go to your projects directory, like ~/Projects, and init a Zola project:

zola init my_website

Also you can navigate into an existing directory, and then just run:

zola init

You might be prompted by things like your website url, if you want to use SASS, and so on, you can change those settings in the generated zola.toml file in the root of your project.

Now you can run your project in local:

zola serve

Now open your browser, and navigate to http://127.0.0.1:1111, it should look something like this:

Initial project structure

Your project structure should look similar like this:

├── content
├── static
├── templates
├── themes
└── zola.toml

I would recommend to create a static/css/main.css.

Base template and home page

Configuration of `zola.toml`

Here is my base configuration, edit it as you like:

base_url = "https://juanmanzanero.com"
compile_sass = false
build_search_index = false
author = "Juan Manzanero"
output_dir = "build"
generate_feeds = true
default_language = "en"

I prefer to use pure CSS instead of SASS, change the output_dir (which is where the generated website files goes) to build.

Create the base template

Create a new file: templates/base.html, this is the body of your HTML page:

 1<!doctype html>
 2<html lang="{{ lang }}">
 3    <head>
 4        <meta charset="UTF-8" />
 5        <meta name="viewport" content="width=device-width, initial-scale=1.0, viewport-fit=cover" />
 6        <title>My website</title>
 7        <meta name="description" content="Hello world">
 8        <link rel="stylesheet" href="{{ get_url(path='css/main.css') }}">
 9    </head>
10    <body>
11        <main class="main-content">
12            {% block content %}
13            {% endblock %}
14        </main>
15    </body>
16</html>

Line 2: is a globally available variable that we will take advantage later, from now, as we set in the zola.toml, default_language = "en", when being in our "home" (/) in the website, the lang will be set to en (English)
Line 8: here we are importing from static/css/main.css our stylesheet, the get_url will be usefull for things like this
Lines 12-13: this is where our dynamic content will be rendered, starting with our home.

Create the home page

New file: templates/index.html:

 1{% extends "base.html" %}
 2
 3{% block content %}
 4    <section class="hero">
 5        <h1>Hello world</h1>
 6        <p>This is my website built with Zola!</p>
 7        <a href="/blog">Blog posts</a>
 8    </section>
 9{% endblock %}

Line 1: here we extend our base.html telling Zola that it will wrap our index.html
Lines 3-9: starting with {% block content %} we then type our HTML content, and close it with {% endblock %}, also add the /blog link that we will use later

Adding content

Zola is focused on building content sites like this one, where you share blog posts or similar stuff.

To define your content, this goes in your content/ directory.

Start by creating content/_index.md:

 1+++
 2title = "My website"
 3description = "Hello world"
 4+++
 5
 6# Hello world.
 7
 8This is my website built with Zola!

Lines 1-4: here we define our frontmatter data, this will be useful for rendering dynamic content
Lines 6-8: markdown content, use markdown syntax to type posts, or whatever you like

Update your `templates/base.html`

Let us change the templates/base.html so it uses the title and description values from our content/_index.md:

 1{% set root_section = get_section(path="_index.md") %}
 2
 3{% if page is defined and page.title %}
 4    {% set title = page.title ~ " | " ~ config.author %}
 5{% else %}
 6    {% set title = config.author %}
 7{% endif %}
 8
 9{% if page is defined and page.description %}
10    {% set description = page.description %}
11{% else %}
12    {% set description = root_section.description %}
13{% endif %}
14
15<!doctype html>
16<html lang="{{ lang }}">
17    <head>
18        <meta charset="UTF-8" />
19        <meta name="viewport" content="width=device-width, initial-scale=1.0, viewport-fit=cover" />
20        <title>{{ title }}</title>
21        <meta name="description" content="{{ description }}">
22        <link rel="stylesheet" href="{{ get_url(path='css/main.css') }}">
23    </head>
24    <body>
25        <main class="main-content">
26            {% block content %}
27            {% endblock %}
28        </main>
29    </body>
30</html>

Lines 1-13: here we are setting some variables:
- root_section: is our content/_index.md we import it
- page: will be use it in the future, that is why are doing a conditional (if else)
- title: if the page variable is defined, we create a our title by combining the page.title value, plus the config.author variable, which is set in the zola.toml file as author = "Juan Manzanero"
- description: just like with title we get description from page.description,
Lines 18-19: as we did with en, we embed our title and description variables

If you check your website, it should look like this:

Our project with the base.html, index.html, and content/_index.md

Do you see the title in the tab bar?

Check your web tools and look for the description tag, the description you typed in content/_index.md will be there.

Adding subpages: /blog

Create content/blog directory, then create a file: content/blog/_index.md:

+++
title = "Blog"
description = "These are my posts"
sort_by = "date"
+++

Create content/blog/hello-world directory, then inside create content/blog/hello-world/index.md file:

+++
title = "Hello world"
description = "My first post!"
date = 2026-09-01
+++

And I did it with [Zola](https://www.getzola.org)

Create templates/section.html, and add the following:

{% extends "base.html" %}

{% block content %}
    {% set content_section = get_section(path="blog/_index.md") %}
    <section class="blog-section">
        <h1>{{ content_section.title }}</h1>
        {% if content_section.description != "" %}
            <p>{{ content_section.description }}</p>
        {% endif %}
        <ul class="posts-list">
            {% for post in content_section.pages %}
                <li class="post-item">
                    <a href="{{ post.path }}">
                        <h3>{{ post.title }}</h3>
                    </a>
                    <time datetime="{{ post.date }}">
                        {{ post.date | date(format="%B %d, %Y") }}
                    </time>
                </li>
            {% endfor %}
        </ul>
    </section>
{% endblock %}

Once again, we extend our base.html, then we add the block content, just like in index.html, also now we import blog/_index.html, this will contain all our posts insde content/blog/, so we can list them.

Then we iterate through the content_section.pages property, as we currently have only one, one post will be displayed with the data we defined in the frontmatter.

It should look like this:

Now add a new template: templates/page.html:

 1{% extends "base.html" %}
 2
 3{% block content %}
 4<article class="post">
 5    <h1>{{ page.title }}</h1>
 6    {% if page.date %}
 7        <time datetime="{{ page.date }}">
 8            {{ page.date | date(format="%B %d, %Y") }}
 9        </time>
10    {% endif %}
11    <p>{{ page.description }}</p>
12    {{ page.content | safe }}
13</article>
14{% endblock %}

It looks like this:

Keep adding posts

Now try adding new posts just like blog/hello-world/index.md, each of them will be created by Zola.

Internationalization (i18n)

This website serves content in both English and Spanish, you can configure Zola for supporting multiple languages.

default_language = "en"

[languages.en]

[languages.es]

This will show content in English if we are in the root page /, and Spanish content if we are in /es.

Still if you visit /es, you will see your orginal content, let us fix that.

Create content/_index.es.md:

+++
title = "Mi website"
description = "Hola mundo"
+++

# Hola mundo

Este es mi website constrido con Zola!

Now update templates/index.html:

 1{% extends "base.html" %}
 2
 3{% block content %}
 4    {% if lang == "es" %}
 5        {% set blog = get_section(path="_index.es.md") %}
 6        {% set blog_url = "/es/blog" %}
 7    {% else %}
 8        {% set blog = get_section(path="_index.md") %}
 9        {% set blog_url = "/blog" %}
10    {% endif %}
11    <section class="hero">
12        {{ section.content | safe }}
13        <a href="{{ blog_url }}">Blog posts</a>
14    </section>
15{% endblock %}

Lines 4-8: we have the lang variable globally available, it retrieves the current language of our page, determinate by the subpath, just like I explained before. Then we import conditionally the respective _index.md file if we are in en (/en) or _index.es.md if we are in es (/es)
Line 10: there we can render our _index.md or _index.es.md content

Let us also update our base.html:

 1{% if lang == "es" %}
 2    {% set root_section = get_section(path="_index.es.md") %}
 3{% else %}
 4    {% set root_section = get_section(path="_index.md") %}
 5{% endif %}
 6
 7{% if page is defined and page.title %}
 8    {% set title = page.title ~ " | " ~ config.author %}
 9{% else %}
10    {% set title = config.author %}
11{% endif %}
12
13{% if page is defined and page.description %}
14    {% set description = page.description %}
15{% else %}
16    {% set description = root_section.description %}
17{% endif %}
18
19<!doctype html>
20<html lang="{{ lang }}">
21    <head>
22        <meta charset="UTF-8" />
23        <meta name="viewport" content="width=device-width, initial-scale=1.0, viewport-fit=cover" />
24        <title>{{ title }}</title>
25        <meta name="description" content="{{ description }}">
26        <link rel="stylesheet" href="{{ get_url(path='css/main.css') }}">
27        <link rel="icon" type="image/x-icon" href="{{ get_url(path='favicon.ico') }}" />
28    </head>
29    <body>
30        <main class="main-content">
31            {% block content %}
32            {% endblock %}
33        </main>
34    </body>
35</html>
36

Update templates/section.html:

 1{% extends "base.html" %}
 2
 3{% block content %}
 4    {% if lang == "es" %}
 5        {% set content_section = get_section(path="blog/_index.es.md") %}
 6    {% else %}
 7        {% set content_section = get_section(path="blog/_index.md") %}
 8    {% endif %}
 9    <section class="blog-section">
10        <h1>{{ content_section.title }}</h1>
11        {% if content_section.description != "" %}
12        <p>{{ content_section.description }}</p>
13        {% endif %}
14        <ul class="posts-list">
15            {% for post in content_section.pages %}
16            <li class="post-item">
17                <a href="{{ post.path }}">
18                    <h3>{{ post.title }}</h3>
19                </a>
20                <time datetime="{{ post.date }}">
21                    {{ post.date | date(format="%B %d, %Y") }}
22                </time>
23            </li>
24            {% endfor %}
25        </ul>
26    </section>
27{% endblock %}

Lines 4-8: again, we conditional fetch our blog/_index.md or blog/_index.es.md, depending of our lang variable

Now create a new file, content/blog/hello-world/_index.es.md:

 1+++
 2title = "Hola mundo"
 3description = "¡Mi primer post!"
 4date = 2026-09-01
 5slug = "hola-mundo"
 6+++
 7
 8Y lo hice con [Zola](https://www.getzola.org).

Line 5: the slug property will change the url name, from /hello-world/ to /hola-mundo

Your page, if you navigate to /es, will look like this:

Conclusion

Now you can add styles in your static/main.css, modify the pages structure, and so on.

In a future post, I will share some advanced techniques and tricks for making it easier work with Zola.