Moving from Pelican to Zola

Feb 11, 2020 ยท #blog #pelican #programming #rust

Last weekend I moved this site over from Pelican to Zola. The motivations were based partly in merit, but partly also just for fun.

The migration itself was mostly painless. The part that took the most amount of time was just converting the posts from Pelican format to Zola format. Even though both expect Markdown, I found that there were some minor differences here and there (the front-matter syntax, for example). But nothing that a quick Python script could not automate.

Pelican / Zola

I've been using Pelican for this site for about 4 years now. When I started out, I chose Pelican because it was (and probably still is) the most popular static site generator written in Python.

And I still think that Pelican is an excellent way of building static sites. You get a lot of features out of the box. The documentation is excellent. And if you need a particular feature that hasn't been implemented yet, it's easy to write a plugin.

I'm not sure if there's any specific disadvantage I can point to. Overall, Pelican has been super nice to work with. I do know that people often complain about themes, but I never had to muck around with installing third-party themes so I can't confirm how valid/invalid those complaints are.

Looking back, I think I switched mostly because I've been trying to pick up Rust in my free time. And I have this weird theory that the more I surround myself with tools written in the language I'm trying to learn, the faster I'll be able to pick the said language up.

There may or may not be some truth to that statement. At least there's a direct analogy to learning languages that humans use to communicate. In the case of machine languages though, the argumentation in my head is kind of arbitrary and the effectiveness remains to be seen. Besides, this site is not some "real-world" project generating revenue, so I don't necessarily have to weigh the trade-offs between development time and product impact. "Playing around" is perfectly fine for a site like this.

So last Friday I went on to StaticGen, and picked up literally the first SSG from the list that was written in Rust. This happened to be Zola.

Installing Zola

The installation "process" was basically just downloading the latest release from Github, and moving the included binary file over to ~/.local/bin. Having spent slightly more than a decade in the Python world where you have to do the virtualenv dance every now and then, this was a nice surprise. To be clear, I don't think I've had huge problems with virtualenv. Combined with Poetry, I still feel it's a reasonable way to manage Python applications. But it's still hard to beat static binaries.

I think the installation would've been even quicker if my distro would have had Zola in the package repositories, but that would be a bit too optimistic of Debian stable. ๐Ÿคทโ€โ™‚๏ธ


One of the next things I was pleasantly surprised about was speed. The fact that Zola is written in Rust means that even without any particular optimizations, it's fast. Like, stupidly fast.

Incremental builds are almost always under 5ms, and building the entire site from scratch takes ~100ms. That's a huge difference from Pelican where even incremental builds can easily take 2-3 seconds.

The Migration

Overall, the transition was fairly painless. The Zola documentation is pretty clear on how to get started and organize things. So the majority of my time was spent on converting the blog posts from Pelican format to Zola format (or rather, writing a script that does that conversion).

While they both use Markdown, the front-matter syntax is different. Plus, tags in Zola are defined as explicit taxonomies using a TOML-like syntax within the front-matter, while in Pelican you can define tags directly like how you define other fields.

I ended up writing a quick Python script to take the content/ directory from a Pelican site and convert all your posts to a format that would be compatible with Zola. This saved me a lot of time.

Please note that I wrote this script for my own personal setup. There's a reasonable chance that it may not work in your case, depending on if you've arranged your content differently or there are slight differences here and there in how your posts are formatted. But it might be worth a shot.

As for the HTML layouts, since I chose to write the theme myself, I had to look up the Tera templating syntax every now and then. Fortunately, it's quite similar to Jinja2, so it wasn't that tricky.


So far I'm happy with the migration. There are a ton of resources on the web warning against rewrites. And most of them are true.

But I think that if the project under consideration is not business critical, and you have some free time on your hands, and you want to play around with some new technology, it's OK to rewrite things. ๐Ÿ™ƒ