Zola to Sphinx

Date: 2025-01-04

Tags: Blog


Switching my blog from Zola to Sphinx.

I’m only 3 posts in, and I’m already switching the static site generator I’m using to blog. The switching cost is low with little content.

Problems with Zola

Zola is great, but I started to run into limitations when writing a blog post with lots of svgbob diagrams.

svgbob takes ASCII diagrams and makes pretty SVGs. For example, this text:

     .---.
    /-o-/--
 .-/ / /->
( *  \/
 '-.  \
    \ /
     '

Becomes this SVG image:

It’s easy to add an extension to call svgbob and convert inline ASCII text to a diagram with other documentation tools such as mdBook and Sphinx. Zola doesn’t have any way to handle inline diagrams that need preprocessing. To use Zola with svgbob diagrams I created a build system to generate SVGs from external text files and put them in the correct location, but this is more cumbersome than I would like.

After using Zola for a month I have some other nitpicks:

  • Zola doesn’t have support for AV1 images: getzola/zola #1202

  • Zola requires using a submodules to manage themes, which isn’t supported in nix flakes: NixOS/nix #11251

    • Another possible solution is git subtrees, but I don’t like how subtrees pollute git history

The nitpicks are minor issues. Zola’s lack of extensibility led me to migrate.

Sphinx

Many large projects use Sphinx and you’ve likely read documentation built with Sphinx such as:

The reason I want to switch to sphinx is the extendability. Sphinx supports custom directives to convert inline text to diagrams at build time. There are already many plugins to use popular tools with Sphinx:

Previously I dismissed Sphinx because:

  1. Sphinx is slow when rendering documentation with many pages

  2. Sphinx made for documentation, not blogging

  3. I wanted to try something new

I shouldn’t have dismissed Sphinx because of the first problem. My blog is tiny, with only a handful of pages, and I don’t plan on writing new posts frequently. Additionally Sphinx is written in Python, which has gotten a lot faster recently. There is likely never going to be enough content in this blog to run into performance issues.

The second problem is solved with an extension for blogging with Sphinx. The ABlog extension handles the blogging aspects for Sphinx, tags, archives, and atom feeds.

Problems with Sphinx

Sphinx is more extendable than Zola, but it’s not perfect. Sphinx still has many disadvantages compared to Zola.

Zola is batteries-included. As a user there are only two dependencies to manage, Zola itself, and a theme. Sphinx requires many extensions to achieve basic functionality. I had to use sphinx-sitemap to generate a sitemap, and sphinx-favicon to support multiple favicon formats.

Migration to Sphinx

The migration itself was straightforward. I spent most of the time theming and configuring to my taste.

I chose the PyData Theme because it met the requirements I set out in Starting a blog. Notably it respected the system dark/light theme, which many Sphinx themes don’t.

The content changes consisted of:

  • Changing blog post metadata formats

  • Changing the markup for images and figures

  • Moving svgbob diagrams inline with Sphinx directives

Redirects

Most, but not all, URLs stayed the same. I felt it was important not to break any existing links that may exist.

There are three extensions that pop-up when searching for sphinx redirects.

I tried all three and found sphinxext.rediraffe to be the easiest to use.

sphinxext.rediraffe is designed for redirecting documentation pages. I was able to redirect everything except the atom.xml feed to its new home at blog/atom.xml. For the feed I instead created a symlink in the nix build.

Conclusion

The transition from Zola to Sphinx was motivated by the need for better extensibility. While Sphinx is more complex than Zola, the wealth of extensions justify the switch.

If you’re reading this then the migration is complete. I hope you like the new theme!

Update 2025-01-05

I changed the theme again.

After checking PageSpeed Insights I noticed that the score for my blog had dropped from a near perfect 99/100 on mobile to a dismal 61/100.

../../../_images/page_speed.png

Page speed after switching to Sphinx with the PyData theme.

This is mostly due to the PyData Theme I chose. After some more digging I found furo, a much lighter theme that works well with javascript turned off.

Unfortunately ABlog and furo didn’t work together out of the box. Both repositories have unresolved issues to support each other since 2021.

I ended up writing my own ABlog replacement to generate pages for tags, archives, and atom feeds.