Migrating from Hugo to Zola

I have been using Hugo for my blog for a while now, and while I have been happy with it, I have been looking for a change. After some research and testing, I have decided to migrate my blog from Hugo to Zola. In this post, I will share my experience with the migration process and some of the reasons behind my decision.

Why I Decided to Migrate

My development journey started with Django. I have been using Django since version 1.6 when I started my career 11 years ago. After working as a Django developer for a long time, I have grown accustomed to its template syntax and structure. While Hugo’s Go templates are powerful, I find Django’s template system more intuitive and easier to work with. The familiarity and clarity of Django templates make development more enjoyable for me, and this was one factor that drew me to explore alternatives to Hugo.

After exploring various static site generators, I settled on Zola for several reasons. First, Zola uses a template syntax similar to Django’s, which felt immediately familiar. While the build times are comparable to Hugo in my case, I appreciate Zola’s simpler and more straightforward configuration. Everything from the directory structure to the template organization feels more intuitive to me. Additionally, Zola comes with built-in syntax highlighting and search functionality out of the box, which were features I had to configure separately in Hugo.

The Migration Process

As I was already using TOML for my frontmatter, the migration process was relatively straightforward. I started by creating a new Zola site and copying over my content files from my Hugo site. I then updated the frontmatter in each file to match Zola’s format and made any necessary adjustments to the content itself. I also had to update my templates to work with Zola’s template syntax, which was a bit more involved but manageable.

There are some differences between Hugo and Zola. For example, the tags and categories taxonomies are handled differently in Zola.

# Hugo
tags = ["Hugo", "Zola"]

# Zola
[taxonomies]
tags = ["Hugo", "Zola"]

Editing all of them would be a pain, so I wrote a small awk script to automate the process. Here is the script:

BEGIN { in_frontmatter=0; has_taxonomies=0; tags="" }
/^\+\+\+/ {
    if (in_frontmatter) {
        if (!has_taxonomies && tags != "") {
            print "\n[taxonomies]"
            print tags
        }
    }
    in_frontmatter = !in_frontmatter
    has_taxonomies = 0
    print
    next
}
in_frontmatter && /^tags = / {
    tags = $0
    next
}
in_frontmatter && /^\[taxonomies\]/ {
    has_taxonomies = 1
    if (tags != "") {
        print
        print tags
        tags = ""
        next
    }
}
{ print }

Save the script as update_frontmater.awk and run it on your content files like this:

find content/posts -name "*.md" -exec sh -c 'awk -f update_frontmatter.awk "$1" > "$1.tmp" && mv "$1.tmp" "$1"' sh {} \;

This script will add the [taxonomies] section to the frontmatter of each content file if it is missing and move the tags field to the [taxonomies] section. I haven’t tested it for all cases so be careful when using it.

Other Additions

I have also taken this opportunity to add Fediverse comments to my blog. I have been using Mastodon for a while now, and I wanted to integrate it into my blog. I found a blogpost by Carl Schwan that explains how to add Mastodon comments to a static site using a simple JavaScript snippet. I followed his instructions and added the snippet to my templates, and now visitors can comment on my posts using their Fediverse accounts. You can try it out by commenting on this post!

Conclusion

The migration from Hugo to Zola was a smooth process overall, and I am happy with the results. Zola’s template system is more intuitive for me, and I appreciate the flexibility it offers. I am looking forward to exploring more of Zola’s features and customizing my blog further. If you are considering migrating from Hugo to Zola, I would recommend giving it a try and seeing if it fits your needs. See you in the next post!