Blog goes Zola

2025-11-28

I found myself building python scripts to convert markdown blogposts I wrote to static html pages with the format of my blog. A few days later, I realized there must be a standard way to do this, surely. A quick google search shows that Hugo and Zola are two common SSGs to do just that. After reading a few blogposts of fellow blog owners who have come across this choice and later on decided to move from Hugo to Zola or the other way round. I chose Zola, mostly because it’s built on Rust, a language I’ve been hearing praise for ages. In addition, it seems that Hugo, built on Go, despite its bigger popularity, is harder and more time demanding to configure, although more versatile.

zola init myblog

After installing the Apollo theme

git submodule add https://github.com/not-matthias/apollo themes/apollo

I just transferred the content of my old blog to this new directory structure. Changing the routes and titles of pages is surprisingly easy and intuitive. It’s all based on TOML:

  • TOML front matter: a set of metadata embedded in a file at the beginning of the file enclosed by triple pluses (+++):
title = ""
description = ""
#...
  • config.toml: a file in the root directory where routes are defined.

A Zola website has a typical structure as follows:

.
├── config.toml
├── content
│   ├── posts
│   │   ├── post-1.md
│   │   ├── post-2.md
│   │   └── _index.md
│   └── projects
│   │   └── _index.md
│   └── _index.md
├── sass
│   └── main.scss
├── static
│   ├── font
│   │   └── custom_font.otf
│   ├── img
│   │   └── img.png
│   └── js
│       └── main.js
│── templates
│   ├── base.html
│   ├── index.html
│   ├── page.html
│   ├── post.html
│   └── section.html
└── themes
    └── apollo

Where:

  • _index.md: a special file at each directory that tells Zola to generate a page structure based on the declared front matter.

  • content: the folder where you write your content. Each file in this folder is a page on your site.

  • sass: the folder where you keep your CSS stylesheets.

  • static: the folder where you keep all your static assets, such as images, fonts, and JavaScript files.

  • templates is the folder where you’ll keep your HTML templates. Once you install a theme, these files serve to overwrite the templates defined in the themes folder.

Veredict🔗

By using a Zola theme, there’s less personality to the blog, but I believe I still made the right choice. The website is very clean, and I can now start to focus on writing and let go of the overhead.

Best features of Zola:

  • Shortcodes: a shortcode corresponds to a template defined in the templates/shortcodes directory that can be used in a Markdown file. It can be use to inject more complex HTML or to make repetitive data tasks easier. So it can be used to inject data in a page from an external file in the JSON, XML, CSV,...format.
  • CommonMark: standard, unambiguous syntax specification for Markdown. Basically, a fine-tuned version of Markdown that behaves consistently across the web.
  • Tera: A powerful, easy-to-use template engine for Rust. It simplifies pages creation by using templates to generate pages from markdown.
  • Filename-based Date Parsing: If a markdown file’s name starts with a date in the YYYY-MM-DD format, the framework automatically extracts this date and sets it as the page date. This simplifies the management of post dates without requiring the user to specify them in the front matter for every post.