Zola quickstart
2024-03-19
This post is one of the first one after a long time, I am evaluating Zola
as replacement of Jekyll, and thought of creating a blog for step-by-step site building.
Whether you like Rust and SSG or you do not know any of these, if you wish to create a website or a blog, Zola
is made for you! We are going to discover here the basic concepts. For more advanced options, please refer to the documentation.
Installation options
macOS
$ brew install zola
It is also available for installation on MacPorts:
$ sudo port install zola
Arch Linux
Zola is available in the official Arch Linux repositories.
$ pacman -S zola
Apline Linux
Zola is available in the official Alpine Linux community repository since Alpine v3.13.
See this section of the Alpine Wiki explaining how to enable the community repository if necessary: https://wiki.alpinelinux.org/wiki/Repositories#Enabling_the_community_repository.
$ apk add zola
Debian
Zola is available over at barnumbirr/zola-debian. Grab the latest .deb
for your Debian version then simply run:
$ sudo dpkg -i zola_<version>_amd64_debian_<debian_version>.deb
Fedora
Zola is avaiable via COPR
$ sudo dnf copr enable fz0x1/zola
$ sudo dnf install zola
FreeBSD
Zola is available in the official package repository.
$ pkg install zola
Docker
Zola is available in docker registry. It has no latest
tag, you will have to install with specific tag pull.
$ docker pull ghcr.io/getzola/zola:v0.17.1
Build
$ docker run -u "$(id -u):$(id -g)" -v $PWD:/app --workdir /app ghcr.io/getzola/zola:v0.17.1 build
You can now browse http://localhost:8080
.
For live reload, use below command:
$ docker run -u "$(id -u):$(id -g)" -v $PWD:/app --workdir /app -p 8080:8080 -p 1024:1024 ghcr.io/getzola/zola:v0.17.1 serve --interface 0.0.0.0 --port 8080 --base-url localhost
Multi-stage build
FROM ghcr.io/getzola/zola:v0.17.1 as zola
COPY . /project
WORKDIR /project
RUN ["zola", "build"]
Serve
$ docker run -u "$(id -u):$(id -g)" -v $PWD:/app --workdir /app -p 8080:8080 ghcr.io/getzola/zola:v0.17.1 serve --interface 0.0.0.0 --port 8080 --base-url localhost
Windows
For windows users, some of the below indicated tools be useful to install zola:
Using Winget:
$ winget install getzola.zola
Also it is available on Chocolatey:
$ choco install zola
and Scoop:
$ scoop install zola
Unfortunately Zola installation isn't possible via Powershell ISE.
Check the Installation
To check if it's working:
$> zola --help
The help screen:
A fast static site generator with everything built-in
Usage: zola [OPTIONS] <COMMAND>
Commands:
init Create a new Zola project
build Deletes the output directory if there is one and builds the site
serve Serve the site. Rebuild and reload on change automatically
check Try to build the project without rendering it. Checks links
completion Generate shell completion
help Print this message or the help of the given subcommand(s)
Options:
-r, --root <ROOT> Directory to use as root of project [default: .]
-c, --config <CONFIG> Path to a config file other than config.toml in the root of project [default: config.toml]
-h, --help Print help
-V, --version Print version
Post installation
Once you have installed Zola, create a site by entering the following in a terminal:
$ zola init quicksite
Answer the interactive question as follows in order to init the config.toml
file:
Welcome to Zola!
> What is the URL of your site? (https://example.com): http://example.com
> Do you want to enable Sass compilation? [Y/n]: Y
> Do you want to enable syntax highlighting? [y/N]: N
> Do you want to build a search index of the content? [y/N]: N
10 milliseconds later, you should get a folder with the following architecture:
$ tree quicksite/
quicksite/
├── config.toml
├── content
├── sass
├── static
├── templates
├── public
└── themes
in this folder, lets enter:
$ zola serve
and look at http://127.0.0.1:1111/ in our browser, and voila!
As mentioned, we can install a theme or create ourselves.
Custimizing site with First theme
Creating a theme is somewhat easy as writing a site by hand. Moreover, it allows you to understand how zola works. If you are in a hurry, you can also install the theme of this tutorial and review it. A default theme is planned by zola community, but is not yet available.
Lets create the index.html
page in the templates/
directory.
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>Zola quickstart</title>
</head>
<body>
<h1>Welcome</h1>
<p>Hello world!</p>
</body>
</html>
If this page is opened in the browser, then it refreshes itself and we see our "Hello world!" message.
Rather than writing the site content directly into the theme, which is like a site-by-hand without Zola, we will use the template engine (tera used by Zola) to fill the site with variables.
Site name
First, to be able to change the name of the site easily, lets add a variable into [extra]
section of the config.toml
file.
[extra]
# put all your custom site variables here
site_name = "Zola Quickstart"
Now, to use this variable, lets replace the title
line in our index.html
.
<title>{{ config.extra.site_name || upper }}</title>
Here, we used the declared config variable and applied a filter to it. To read more about Tera, please check out the documentation.
Markdown content
It is always a good to be able to manage content independently of the theme whether you are managing a website or a blogsite. Part of this section, we will write content in Markdown. First lets create a welcome text for our site in _index.md
file in content/
directory.
+++
title = "Welcome, you"
description = "welcome message"
+++
Hello world!
and change the index.html
file to handle this content,
<body>
<h1>{{ section.title }}</h1>
<p>{{ section.content | safe }}</p>
</body>
Page reloads and you can see the content of the _index.md displayed via theme index.html file. Now, We have separated the theme and content. Please note, the name used for the markdown file and the name of the variable used to access the data.
Content Structure
If you look at the overview of the Zola, it can be simple to understand tree structure and its purpose.
.
└── content
├── _index.md # https://example.com/
├── blog
│ ├── _index.md # https://example.com/blog/
│ ├── hello-world.md # https://example.com/blog/hello-world/
│ ├── my-first-post.md # https://example.com/blog/my-first-post/
│ └── zola-is-great.md # https://example.com/blog/zola-is-great/
│
├── wiki
│ ├── _index.md # https://example.com/wiki/
│ ├── how-to-build.md # https://example.com/wiki/how-to-build/
│ ├── deploy-advice.md # https://example.com/wiki/deploy-advice/
│ └── contrib-guide.md # https://example.com/wiki/contrib-guide/
│
├── about.md # https://example.com/about/
├── contact.md # https://example.com/contact/
└── cv.md # https://example.com/cv/
All the .md
files are "pages" except for the special file called _index.md
- which contains "sections". These 2 objects just differ in the variables accepted in their header, the section in TOML format - is delimited by "+++" at the top of the file.
Page front-matter
For more details, please refer to Zola documentation dedicated section:
Overall below mentioned fields to can be in page "section":
title = ""
description = ""
date =
weight = 0
draft = false
slug = ""
path = ""
aliases = []
in_search_index = true
template = "page.html"
[taxonomies]
tags = ["tag-1", "web"]
[extra]
Section front-matter
For more details, please refer to Zola documentation dedicated section:
Some of the expected fields in section:
title = ""
description = ""
sort_by = "none"
weight = 0
template = "section.html"
page_template =
paginate_by = 0
paginate_path = "page"
insert_anchor_links = "none"
in_search_index = true
render = true
redirect_to = ""
transparent = false
aliases = []
[extra]
Expandable template
The interest of a template is to maximize code reuse. Let's discover how to use the basic features in a simple example.
<!-- index.html -->
<!doctype html>
<html lang="fr">
<head>
<meta charset="utf-8"/>
<title>{{ config.extra.site_name | upper }}</title>
</head>
<body>
{% include "nav.html" %}
{% block content %}{% endblock content %}
</body>
</html>
Here We've discovered that the include tag which allows to include another template and the block tag which allows to declare a block which will be replaced by the templates which derive from it.
<!-- nav.html -->
<nav>
<ul>
<li> <a href="{{ get _url(path="@/_index.md") }}"> Home </a> </li>
<li> <a href="{{ get _url(path="@/contact.md") }}"> Contact </a> </li>
<li> <a href="{{ get _url(path="@/about.md") }}"> About </a> </li>
</ul>
</nav>
Here We've discovered that the get _url
function which allows to obtain the URL of a page in the site, and the notation @/file which allows to make an internal link to a page of the site.
{% extends "index.html" %}
{% block content %}
<h1>{{ page.title }}</h1>
<p>{{ page.content | safe }}</p>
{% endblock content %}
Here We've discovered that the `extends' tag which allows to derive from an existing template to replace one or more blocks.
<!-- section.html -->
{% extends "index.html" %}
{% block content %}
<h1>{{ section.title }}</h1>
<p>{{ section.content | safe }}</p>
<p>Pages in section</p>
<ul>
{% for page in section.pages | reverse %}
<li>
<em> <a href="{{ page.permalink }}"> {{ page.title }} </a> </em>
<span>{{ page.date | date(format="%Y-%m-%d") }}</span>
</li>
{% endfor %}
</ul>
{% endblock content %}
Here We've discovered that the for tag which allows to make a loop in a list of elements and filters like date which can take arguments.
# contact.md
+++
title = "contact"
date = 2024-03-18
+++
Contact me at ...
Here We've discovered that an additional metadata indicating the date of the page.
# about.md
+++
title = "about"
date = 2019-09-25
+++
This site has been made with :
- Zola
- Sass
- TOML
Here We've discovered that a Markdown list will be rendered as an HTML list.
A bit of colour
SASS is a kind of CSS without punctuation of type {, ;
and a variable management. It is used by many css frameworks. If you don't want to use it, you can of course write css files directly and jump to the next section.
SASS
Lets enjoy a very nice feature of Zola: the Sass compilation. Lets add the line
<link rel="stylesheet" href="{{ get _url(path="extra.css") }}"/>
in the head of our index.html
and add the file extra.sass
to the root of our sass folder.
$bg: #111
$cl: #0f0
nav ul li
display: inline-block
margin-left: 10px
border: solid 1px #666
body
color: $cl
background-color: $bg
a
color: #a5a
CSS
To add CSS to our theme, we just need to add this line
<link rel="stylesheet" href="{{ get _url(path="extra.css") }}"/>
in the
of ourindex.html
file and add the extra.css
to the root of our static/
directory.
nav ul li{
display: inline-block;
margin-left: 10px;
border: solid 1px #666;
}
body {
color: #0f0;
background-color: #111;
}
a{
color: #a5a;
}
For the future
In short, this post is to get you started on building your own Zola site - introducing to some of the key concepts. Hope you continue exploring Zola!