I started migration of my old blog from Hugo to Zola. Both of these are static site generators; Hugo is built with Go, whereas Zola is built with Rust.

Reason

There were a few. But before I get into any detail, a full disclosure:

There were no hard-core architectural decisions made during this migration process.

Here's a quick outline of what led to this migration:

1. Getting used to the Rust ecosystem
2. Finding contribution opportunities in Zola
3. Switching to Cloudflare
4. Registering a custom domain https://thepoetdj.dev
5. Creating a design system from scratch, and
6. Writing, improving and sharing my knowledge

If this piqued your interest, then let's dive right in.

Why Rust?

Even though I am a full-stack engineer by profession, a lot of my time is spent around the Java ecosystem. It shouldn't come as a surprise that I am used to its automatic garbage collection capabilities. However, I've always wanted to get my hands dirty with a low-level language.

It was around last year when I was working on one of our data engineering applications with Apache Spark that I came across various articles referencing Rust as part of the modern data engineering stack. That, along with its unique memory safety approach, increased my curiosity about the language.

My mind was made up by the end of February 2025 to learn Rust. Having came from a high-level language background like Java, I would say that this learning experience has been quite steep, but I'll leave that discussion for another time.

Why Zola?

To be very honest, my initial reasoning behind using Zola was because it was built with Rust.

I did do some research, compared it with other popular static site generators like Hugo and Jekyll, before making a final decision of migrating to it. And I must say, the process was very smooth.

Part of the reason for this smooth transition was because there were only 3 technical articles on the old site, excluding the 2 which were neither technical nor did I consider them during this transition. The articles that I did migrate had different type of UI elements that required distinct styles, which I'm going to discuss later in a separate section.

Exploring contribution opportunities

My major focus while designing the custom theme in Zola was to identify various areas of improvement, so that I can check with the community if anyone else had faced a similar challenge, and if I can probably contribute a solution for that.

I do have found a place to add a new feature, but that is specific to the theme that I am building. And perhaps, there is always a chance that someone already has opened an issue for that.

Choosing Cloudflare

Journey with GitHub Pages

Back when I had started the old blog, GitHub was the most frequent place that I visited every now and then. And I still do!

I was intrigued by the concept of GitHub Pages, where one would only have to create a public repository of the form username.github.io. And with just that any HTML content that you push to that repository gets deployed and becomes accessible at https://thepoetdj.github.io, as long as you have the index.html file at its root.

It became obvious to me at that time to host a static site with GitHub Pages without having to register a separate domain. The only restriction I had was to keep the repository public in the Free plan.

Why Cloudflare?

Over the years we saw many platforms provide options to host static and even dynamic sites, like Netlify and Vercel. Cloudflare also introduced Cloudflare Pages around the end of 2021.

What I liked about Cloudflare Pages was that:

1. I can keep my repository private, and
2. I can give it any name that I want, and, the best part
3. I only have to keep the source of the static site

The last point-keeping only the source of your static site in the private repository-is the most interesting one.

You see, when using GitHub Pages, you have to keep the generated static site in your repository instead of the source code that built your static site.

For example, you can create a repository named ssg.username.github.io to keep the actual source code of your static site in any SSG that you like, and then build and push the final HTML content to a repository named username.github.io. This is what I used back in 2018-19.

Compared to that, with Cloudflare Pages, the only repository I keep is ssg-blog (just an example). The Cloudflare Pages deployment takes care of the rest when I push any changes or new content to the target branch.

Support for Zola

I have observed the zola: not found error during build phase, and even though it is mentioned on the Cloudflare Pages documentation, I do not see it working without the workaround provided here.

Why register a custom domain?

Simple. I always wanted to have my own domain name.

Although Cloudflare Pages does provide a domain name like project.pages.dev on successful deployment of your project.

There is a free option available for you if you do not wish to register a domain yet, and the default URLs provided by GitHub Pages or Cloudflare Pages is not your preferred choice. Have a look at is-a.dev, they provide a free subdomain of the form user.is-a.dev.

Custom Theme Design

Part of my decision of using Zola came from designing a custom UI from scratch for my blog. As I mentioned earlier that mostly I engineer solutions on the backend, and a very small amount I spent is on the frontend. I wanted a change in that.

However, I put some hard rules while designing this theme:

• Use HTML and CSS only
• No JavaScript, you can inspect and check the Sources of this or any other page of this site
• And a very interesting one being - not using CSS classes, and relying only on the HTML markup and tag attributes

Going class-less

What I have observed with this one rule is that not having the leverage of using CSS classes forces one to think how to structure the content based on the tag hierarchy. You are required to use each HTML tag for the very purpose that it was made for.

You may have come across this situation where you end up using a lot of <div> tags. As an example, the alerts that you would normally create:

<div class="alert alert-warning">
I'm warning you!
</div>

vs the alerts that you can implement using class-less approach:

<blockquote data-alert="warn">
You have been warned!
</blockquote>

In the class-less version, you are using the <blockquote> element to define your alert which is accompanied by data-alert="warn" attribute. With this attribute you end up providing additional information about your blockquote element, which can be utilized by custom JavaScript at a later stage, or can be used as a target selector in your CSS as follows:

blockquote {
  ...
  &[data-alert="warn"] {
    background-color: var(--color-warn);
    border-left-color: var(--color-warn-border);
    ...
  }
...
}

Conclusion

I like the progress I've made so far with this decision of migrating to Zola, with a custom theme and using Cloudflare Pages. There is always room for improvement. And sooner or later, I will make this theme publicly available on the Zola Themes page.

Until next time!