My updated thoughts on Zola – version 0.23
I really feel like writing some words about my experience managing this website after Zola release 0.23 and the next steps from here. This blog is mostly going to be a critique of Zola static site generator and how my opinion has changed in over a year of using.
As you may or may not know, since May 2025 this website has been made with Zola, a static site generator written in Rust. In general, I’ve been pretty happy with Zola. It allowed me to create this website with way less effort put into mundane template-related things and focusing more on the actual content side.
One of the issues I had with Zola since the very beginning, however, has been that the developer of the project seemingly didn’t think that writing proper documentation is a priority. Docs were not easy to navigate, confusing in some areas, and not particularly helpful when just getting started with the project so I had to learn a lot of things from looking at other people’s Zola websites rather than the docs.
That was annoying, but I managed, and once I got a pretty good understanding of how things work, it didn’t bother me anymore.
That is until the release 0.23.0 has been made.
All the things that are wrong here
Release 0.23 introduces a lot of major breaking changes, most of which are related to Tera (the underlying templating engine) being updated to version 2.0 – Tera is made and maintained by the same person making Zola.
Breaking changes in themselves are not the end of the world. Especially with your passion project that evolves as it grows, oftentimes you find yourself having to do some fundamental changes and that’s okay. But only as long as you put the effort into properly communicating and documenting these changes. And as I mentioned before, the author of Zola doesn’t seem to find documentation and communication to be important values.
Version 0.23 got released without any proper announcement beforehand, there is no migration guide at all other than undetailed changelog notes that miss out on half of the changes you will need to take into consideration while making the switch, and documentation website didn’t receive nearly any updates other than blunt removal of pages related to features that have been dropped. Yes, not changed, marked as out-of-date or provided with migration suggestions. Just removed.
Very similar issues are the case with Tera itself – 2.0 migration guide exists, but it doesn’t go into half of the details that it should, updated documentation if of – let’s say – questionable usability (it was bad before as well) and misses some of the built-in features that have been previously documented and still exist in the code, but the author seemingly forgot about them (sic) – which is impressive for a project written in Rust.
And it all makes creating a project relying on that software a massive pain in the ass because you may never know what to expect, but when changes happen you won’t know what changed either 👍️
So you want to update it too
My honest recommendation: just don’t. Look into something else, probably like Hugo or a different static site generator of this kind.
I have no trust in the author of this software to maintain it in a way that isn’t going to be a constant struggle and fishing for information about the way it works, so I’m not going to keep using it and I recommend anyone who is using Zola to migrate away from it. It’s not something you should be using, period.
Obviously I do not ask for an enterprise-grade degree of documentation and care for introducing changes, but this level of recklessness in managing a project that is potentially used by thousands of people (over 17 thousand starts on GitHub as of now didn’t come from nowhere) is not acceptable to me and it shouldn’t be to you either.
What I’m going to do next
As for myself, I haven’t decided what to do next yet.
I’ll either be switching this website to a different static site generator that is being maintained a little bit more thoughtfully or (more likely to be honest) just make it my own project that fits my needs.
Cheers.