Bits of networks

Bits of networks

Networking, system, research

19 Jan 24

Moving from Pelican to Zola

I have been using Pelican for almost 10 years for this blog. It's very good and does the job, but I do find it a bit complex to use, and I wanted to switch to a new theme, so I looked at alternatives. Among the current alternatives, Zola clearly emerged as the simplest and most efficient solution.

From Pelican ...

I must admit that Pelican is still working fine after 10 years, which is quite a feat for a Python project.

However, over time, I found it was not that intuitive to use, mostly because I write blog articles very infrequently. Each time, I had to remember how it works: do I have to use the Makefile or the script? Did I have a virtualenv somewhere or is it a global install? Why is there a specific config file for publishing? I had to reinstall Pelican, and now it is complaining that some of my configuration is deprecated (but amazingly, my old Pelican configuration from 2014 still works without any change)

But the real reason to switch is the theme. I don't like HTML/CSS, so I was quite happy with a very basic Pelican theme at the time, but it is showing its age now. While looking for a newer Pelican theme, I found nothing that I liked much. So, time to switch! Since Deuxfleurs is using Zola a lot and it seems really simple to use, I went this route.

... to Zola

Most tools advertise themselves as "easy to use", but that often means "easy to use for the authors". But in the case of Zola, it is actually impressively easy to use. Having a single binary instead of having to play with virtualenvs: a big win. Having just two main commands zola serve and zola build: a big win. There are many great themes to use as a base, and extending themes is simple and really well documented.

Keeping compatibility with old URLs

While migrating my content, I encountered a difficulty to maintain compatibility with the old URLs. I would like to avoid breaking URLs to old articles.

Pelican generates URLs such as /blog/my-article-slug.html. But Zola would generate /blog/my-article-slug/ instead, by putting the content in a index.html file within that directory. This behaviour is currently not configurable.

Given this, keeping compatibile URLs seemed like an impossible task, but there is actually a way if you are a bit creative with aliases. You just have to add an alias with the old name in the front matter of your article:

title = "My page title"
aliases = ["posts/old-page-name.html"]

This will still generate the file as usual for Zola (let's say blog/my-page/index.html, exposed as /blog/my-page/), BUT it will also generate a redirect page at /posts/old-page-name.html. This way, old URLs still work and they redirect to the new URL.

Check issue #840 for more details.

Theme fork

I chose the jimmyff/zola-inky theme because it fits my requirements: it's very simple but elegant. In addition, I really like the way it lists articles by year, and the fact that you can show a small excerpt of each article in this list.

However, it was missing a few things for my use-case, so I forked it to add the following features:

  • styling for tables
  • allow to override the content of footers easily
  • use a different set of icons (I needed the Mastodon logo)
  • stop loading external fonts from Google and scripts from CDN

The fork is available here. I should find time to try to upstream some of these changes.

In addition, I changed the style of tags, but this is a local change for my blog, not part of the theme (it feels too specific).