Learn how to – Install and Use Zola Static Site generator

Learn how to – Install and Use Zola Static Site generator.

A static site generator (SSG) is a tool that generates a full static HTML website based on raw data and a set of templates. Zola is one such tool similar to Hugo, Pelican, and Jekyll. It is written in Rust and uses the Tera template engine, which is similar to Jinja2, Django templates, Liquid, and Twig. Content is written in CommonMark, a strongly defined, highly compatible specification of Markdown. Source: Zola Website

It should be noted that compared to other sites, static sites are thus very fast and require no databases, making them easy to host. In this guide, we are going to install and use Zola to create a simple static page. Before anything else, we should begin by installing it then we shall proceed to create and populate out static site.

Installing Zola on Linux | macOS

The team at Zola have done a fantastic job by making sure that many distributions and operating systems can have access to Zola with ease. We can install Zola as follows on various platforms.

macOS

If you are on a mac, you can grab Zola from Brew thus:

brew install zola

Arch Linux

Devout users of Arch Linux will have something to say when we inform them that Zola is available in the official Arch Linux repositories. One simple command is enough to download it and install. Run the following command to get it done.

sudo pacman -S zola

Alpine Linux

For those who prefer Alpine Linux, Zola is available in the official Alpine Linux repository, only on the edge version for now. So you can install it as follows:

apk add zola --repository http://dl-cdn.alpinelinux.org/alpine/edge/community/

Fedora

To all Fedora lovers, you are not left behind. Zola has been available in the official repositories since Fedora 29! Grab it in your machine/server like so:

sudo dnf install zola

Void Linux

Fans of void, here is your time. You will be pleased to hear that Zola is available in the official Void Linux repositories. So you will simply install it like other applications like this:

sudo xbps-install zola

FreeBSD

Nevertheless, FreeBSD is not left behind. Zola is available in the official package repository. All users of FreeBSD and would like to use Zola can install it as simply as running this command:

pkg install zola

OpenBSD

Moreover, Zola is available in the official package repository of OpenBSD. To get it installed on OpenBSD Operating System, running the command below is sufficient.

doas pkg_add zola

Snapcraft

If for one reason or another you cannot find Zola in any of the repositories like in Ubuntu, you can use Snap store. Zola is available on snapcraft and assuming you have snap installed you can install Zola as follows:

sudo snap install --edge zola

Using Zola Static Site generator

Depending on the Operating System or distribution you are currently using, we believe that Zola is now installed and ready to get to use. As you might guess, we will immediately jump into the details of how Zola works and we shall do that by making a simple site. With the example, we hope it will become easier for you to build upon it and make your fully fledged websites. Let us begin:

Step 1: Initialize your blog or website

The first step is to initialize your blog or website because unlike some Static Site Generators, Zola makes no assumptions regarding the structure of your site. You will be asked a couple of questions so that Zola will figure out how it will order most of the things that you need. Initialize your site as follows. You can replace “learnhowtoite” with any name you like.

cd ~
zola init learnhowtoite

The following questions will ensue after you run that command

> What is the URL of your site? (https://example.com): //ownyourlife.com.ng
> Do you want to enable Sass compilation? [Y/n]:
> Do you want to enable syntax highlighting? [y/N]:
> Do you want to build a search index of the content? [y/N]:

Done! Your site was created in /home/vagrant/learnhowtoite

Once you are done answering the questions you should now have a “learnhowtoite” directory with the following structure:

├── config.toml
├── content
├── sass
├── static
├── templates
└── themes

To prove that our Zola is working, we can start the Zola development server with the following command:

$ cd ~/learnhowtoite
$ zola serve -i 172.23.209.227
Building site...
-> Creating 0 pages (0 orphan), 0 sections, and processing 0 images

When you open your browser and pint id to the domain name or IP Address of your server (http://Domain Name|IP Address:1111). If your server is in a remote location and you have a firewall running, you should allow port 1111. You should see a page similar to the one shared below.

Step 2: Create Sample home page

As it had been mentioned in the introductory section of this guide, Zola uses the Tera template engine, which is similar to Jinja2, Django templates, Liquid, and Twig. We are going to see how this templating engine works here. Let us navigate to the templates directory then create a base template that other pages will re-use.

$ cd ~/learnhowtoite/templates
$ vim base.html

<!DOCTYPE html>
<html lang="en">

<head>
  <meta charset="utf-8">
  <title>ComputingForGeeks Blog</title>
</head>

<body>
  <section class="section">
    <div class="container">
      {% block content %} {% endblock %} ##This section takes advantage of Tera templating engine. Other pages will be injected here.
    </div>
  </section>
</body>

</html>

This base template can be extended by other pages so that the repetitive sections are simply handled by this base page. Other pages will focus on the specific functionality they are designed to do. To see how this is done, let us create an index page that will extend this base template.

Within the same templates directory, create index.html file

{% extends "base.html" %}
{% block content %}
<h1 class="title">
  ComputingForGeeks page extending the base template using Tera templating engine.
</h1>
{% endblock content %}

The text between the {% block content %} and {% endblock content %} tags will be injected into the base template.
At this point if we fire up our zola server and visit http://Domain Name|IP Address:1111, we shall see a page like below:

Step 3: Adding some content

In Zola, there is something called a “section“. A section is created whenever a directory (or subdirectory) in the content directory contains an “_index.md” file. If a directory does not contain an _index.md file, no section will be created, but Markdown files within that directory will still create pages (known as orphan pages).

Before we proceed, we will start by making a “site” subdirectory in the content directory then create an “_index.md” file inside it.

This file tells Zola that “site” is a section, which is how content is categorized in Zola.

mkdir ~/learnhowtoite/content/site

Inside the _index.md file, we have an opportunity to pass some variables that we can use in our pages. Therein, let us set the following variables in TOML format:

$ cd ~/learnhowtoite/content/site
$ vim _index.md
+++
title = "Glossary of Geeks blog posts"
sort_by = "date"
template = "site.html"
page_template = "site-page.html"
+++
##Blog Posts Here

Step 4: Create Site Templates

Now that we have informed our “_index.md” file to look for “site.html” template as the base template for listing the Markdown files in this section, and load “site-page.html” as the template for individual Markdown site files, let us go ahead and create these files in “templates” directory.

$ cd ~/learnhowtoite/templates
$ nano site.html
{% extends "base.html" %}
{% block content %}
<h1 class="title">
  {{ section.title }}
</h1>
<ul>
  {% for page in section.pages %}
  <li><a href="{{ page.permalink | safe }}">{{ page.title }}</a></li>
  {% endfor %}
</ul>
{% endblock content %}

site.html extends base.html, but this time we are using this template to list the blog posts. The title we set in the _index.md file above is available to us as {{ section.title }}. In the list below the title, we loop through all the pages in our section (site directory) and output the page title and URL using {{ page.title }} and {{ page.permalink | safe }}, respectively.

At this point, when we fire up zola server and point our browser to http://Domain Name|IP Address:1111/site, we should just see the title as follows:

Step 5: Create Markdown Content

The pages we will be loading in the section area are in markdown format and they shall be within the “site” directory. In the site directory, create a file called blog1.md with the following contents:

$ cd ~/learnhowtoite/content/site
$ nano blog1.md
+++
title = "My first web page"
date = 2021-04-18
+++

This is my first blog post for computing for geeks.

The title and date will be available to us in the site-page.html template as {{ page.title }} and {{ page.date }}, respectively. All text below the closing +++ will be available to us as {{ page.content }}.

At this point, when we fire up zola server and point our browser to http://Domain Name|IP Address:1111/site, we should see the title and the first markdown file title as a hyperlink like so:

Let us add the site-page.html file in the same location

{% extends "base.html" %}
{% block content %}
<h1 class="title">
  {{ page.title }}
</h1>
<p class="subtitle"><strong>{{ page.date }}</strong></p>
{{ page.content | safe }}
{% endblock content %}

After adding this template, we can fire up zola server and when we point our browser to http://Domain Name|IP Address:1111/site/bolg1, we should see the entire markdown file content as illustrated below:

Step 6: Deploying Ready Files

After we finish to style and tune or blog, it is time to display it to your friends. Zola server can be used to build your site with the “zola build” command. The command creates the site inside the public/ folder which you can can easily copy it in your webserver, Vercel, Netlify, GitHub Pages etc.

This is the final file structure for this explored example.

├── config.toml
├── content/
│   └── blog/
│       ├── _index.md
│       └── blog1.md
├── sass/
├── static/
├── templates/
│   ├── base.html
│   ├── site-page.html
│   ├── site.html
│   └── index.html
└── themes/

Concluding Remarks

That is just the tip of the iceberg about Zola. It comes packaged with so much more such as themes, integration with CSS Frameworks, and much more. You can find out more about Zola in its Main Webpage as you brace to get good at this wonderful static site generator.