Create simple blog with Zola

投稿日: 2022-08-11 カテゴリー: tech

Table of Contents

Installation
Create website
Uploading to server
What next?

When I first started using static site generator Zola, it really confused me at first. So I want to share some of my experience with it and create a basic website in this tutorial.

I just wrote this based on the official documentation so it is worse and lack some details.

Installation

There are pre-built binaries for Linux, Windows and MacOS on release page.

If you are using Linux, it should be in the repository so install it with the package manager. I am using Arch-based distribution so installed it with

sudo pacman -S zola

Create website

Run

zola init website

in your terminal. This will give you a prompt which asks some settings of your site. Keep in mind that you can change these settings later in config.toml. If you are not sure which you should answer, follow like this.

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

Sass compilation is a very modern way to write CSS but we really don't need it so disable it. Syntax highlighting will highlight your codes. Building search index is complicated, and if you don't know what you are doing just disable it.

This will create a folder named website in your current directory containing these folders and files.

[shuto@laptop ~/website]$ tree 
. 
├── config.toml 
├── content 
├── static 
├── templates 
└── themes 
4 directories, 1 file

content folder contains markdown files. static can have any files. You can have images, CSS or JavaScript files which you can use. templates is for Tera templates which will render the website. themes is for using themes. You can find various themes at here. If you are not planning to use themes you can delete this folder.

At the end, we would have folder structure looking like this.

[shuto@laptop ~/website]$ tree 
. 
├── config.toml 
├── content 
│   ├── blog 
│   │   ├── first.md 
│   │   ├── _index.md 
│   │   └── second.md 
│   └── _index.md 
├── static 
├── templates 
│   ├── base.html 
│   ├── blog.html 
│   ├── index.html 
│   └── page.html 
└── themes 
5 directories, 9 files

Create base.html in templates directory with following contents.

<!DOCTYPE html>
<head>
    <meta charset="utf-8">
</head>
<body>
    <header>
        <nav>
             <ul>
                <li><a href="/">Home</a></li>
                <li><a href="/blog">Blog</a></li>
            </ul>
        </nav>
    </header>
    <main>
        {% block content %} {% endblock %}
    </main>
</body>
</html>

This will be the base of all of the .html files which which will inherit it. By writing the <header> and <footer> here, you do not have to write them for every file.

Next make index.html in the same directory with this

{% extends "base.html" %}
{% block content %}
{{ section.content | safe }}
{% endblock content %}

{{ section.content | safe }} tells Zola to use the content in the .md file. The markdown file which will be used is _index.md.

Add _index.md to content directory.

+++
+++

# Welcome to my website

This is my website. Thanks for stopping by.

This file defines the content and metadata. It is not required to write section variables inside of +++ (like title = "My webpage"). However, it is required to write opening and closing +++ inside of the .md file. If you don't do this Zola can't create webpage.

Look for the documentation of section variables and page variables to know what variables you can use.

Now let's open a new terminal and run

zola serve

Make sure to run this in the folder which you have created (website in this case). Open http://127.0.0.1:1111/ with your browser. Keep this terminal open since we are going to use it later.

You can see that your website is working!

Next we are going to add a blog section which lists all sorts of blog posts. Create blog sub directory in content directory and add _index.md in blog.

+++
title = "Blog"
sort_by = "date"
template = "blog.html"
page_template = "page.html"
+++

title = "Blog" will be a variable used later. sort_by = "date" tells to sort posts by date. template = "blog.html" will be the base of the listing the markdown files in this section. page_template = "page.html" will be the base of the individual markdown files in the blog directory.

Create blog.html in templates directory.

{% extends "base.html" %}

{% block content %}
<h1 class="title">{{ section.title }}</h1>
<div id="post-list">
    {% for page in section.pages %}
    <div id="post-summary">
        <h2><a href="{{ page.permalink | safe }}">{{ page.title }}</a></h2>
        <small><i>{{ page.date }}</i></small>
        {{ page.summary | safe }}
        <a href="{{ page.permalink }}">Read more...</a>
    </div>
    {% endfor %}
</div>
{% endblock content %}

Go to http://127.0.0.1:1111/blog. You will see the title but no posts. So let's add some contents.

We need to make page.html in templates directory.

{% extends "base.html" %}

{% block content %}
<h1 class="title">{{ page.title }}</h1>
<p>
    <i>{{ page.date }}</i>
</p>
{{ page.content | safe }}
{% endblock content %}

Now create some markdown files which will inherit the page.html.

Create first.md in content/blog as following

+++
title = "First blog"
date = 2022-08-10
+++

This is my first blog.
<!-- more -->

and second.md

+++
title = "Second blog"
pdate = 2022-08-11
+++

This is my Second blog.
<!-- more -->

in the same directory. Note that  is for specifying the content of {{ page.summary }} which is used in the blog.html.

Now we can see our blog posts at http://127.0.0.1:1111/blog. Nice.

Uploading to server

After you created the website all you need to do is generate html files and upload to the remote server. Run

zola build

to generate html files. This will create bunch of files including images, html, css inside of public directory.

I assume you have already setup a basic nginx server here. We will use rsync for uploading to the remote server. Run

rsync -uvrP --delete-after ~/website/public/ username@yourdomainorip:/some/random/directory

Look up for the rsync manual for explanation of the flags used here. Be careful with trailing slash since rsync will create a directory.

I usually create a shell script like this for automating my build and upload.

#!/bin/sh

zola --root ~/code/website build &&
rsync -uvrP --delete-after ~/code/website/public/ username@yourdomainorip:/some/random/directory

What next?

Learn more about Zola
Make your website fancier