Jose Garcia

Migrating from WordPress to Zola: A Practical Guide

2025-11-21T00:00:00+00:00

I recently migrated a WordPress blog that had been running for years to Zola. The process took about a weekend, and the results were worth it: faster load times, zero maintenance overhead, and complete control over the output. Here's everything I learned.

Why Leave WordPress?</h2>

WordPress is powerful, but that power comes with weight. My site was:

Running on a VPS that needed updates and monitoring</li>
Using multiple plugins that occasionally broke after updates</li>
Loading slowly despite caching plugins</li>
Vulnerable to security issues requiring constant vigilance</li>

Costing monthly hosting fees</li> </ul>

The blog was 95% static content. I wasn't using most of WordPress's dynamic features. A static site made more sense.

Understanding What You're Trading</h2>

What you lose:

Dynamic comments (replaceable with external services)</li>
Admin dashboard for editing (you'll edit markdown files)</li>
Plugin ecosystem (you build what you need)</li>
WYSIWYG editor (you'll write in markdown)</li>
Easy updates from browser (you'll push to git)</li> </ul>
What you gain:

Near-instant page loads</li>
Zero server maintenance</li>
No security vulnerabilities</li>
Free hosting options (GitHub Pages, Netlify, Cloudflare Pages)</li>
Complete control over output</li>
Version control for all content</li>
Ability to work offline</li> </ul>
If you write in markdown and are comfortable with git, this trade-off is favorable.
Step 1: Export Your WordPress Content</h2>
WordPress has a built-in export tool:

Go to Tools → Export in WordPress admin</li>
Select "All content"</li>
Download the XML file</li> </ol>
This gives you a file with all posts, pages, comments, and metadata.
You can also use plugins like "WordPress to Jekyll Exporter" which exports directly to markdown, though you'll still need to adapt the format for Zola.
Step 2: Convert Content to Markdown</h2>
WordPress exports to XML. Zola needs markdown with front matter. You have options:
Option A: Use an existing converter
Tools like wordpress-export-to-markdown</code> (npm package) can help:
npm install -g wordpress-export-to-markdown wordpress-export-to-markdown --input=export.xml --output=content/blog </code></pre> Option B: Write a conversion script I wrote a Python script to process the XML and convert to Zola-compatible markdown: import xml.etree.ElementTree as ET from html2text import html2text from datetime import datetime import os import re def clean_filename(title): # Convert title to valid filename filename = title.lower() filename = re.sub(r'[^a-z0-9]+', '-', filename) return filename.strip('-') def convert_wordpress_export(xml_file, output_dir): tree = ET.parse(xml_file) root = tree.getroot() # WordPress XML namespaces namespaces = { 'content': 'http://purl.org/rss/1.0/modules/content/', 'wp': 'http://wordpress.org/export/1.2/' } for item in root.findall('.//item'): # Get post data title = item.find('title').text post_type = item.find('wp:post_type', namespaces).text status = item.find('wp:status', namespaces).text # Only process published posts if post_type != 'post' or status != 'publish': continue # Get content content_html = item.find('content:encoded', namespaces).text or '' content_md = html2text(content_html) # Get metadata date_str = item.find('wp:post_date', namespaces).text date = datetime.strptime(date_str, '%Y-%m-%d %H:%M:%S') # Get categories and tags categories = [] tags = [] for category in item.findall('category'): domain = category.get('domain') name = category.text if domain == 'category': categories.append(name) elif domain == 'post_tag': tags.append(name) # Create filename filename = f"{date.strftime('%Y-%m-%d')}-{clean_filename(title)}.md" filepath = os.path.join(output_dir, filename) # Create front matter front_matter = f"""+++ title = "{title}" date = {date.strftime('%Y-%m-%d')} """ if categories: front_matter += f"\n[taxonomies]\n" if tags: front_matter += f'tags = {tags}\n' if categories: front_matter += f'categories = {categories}\n' front_matter += "+++\n\n" # Write file with open(filepath, 'w', encoding='utf-8') as f: f.write(front_matter + content_md) print(f"Converted: {title}") # Usage convert_wordpress_export('export.xml', 'content/blog') </code></pre> Install required package: pip install html2text</code> This script: Parses the WordPress XML</li> Converts HTML content to markdown</li> Creates proper front matter</li> Organizes files with dates in filenames</li> Preserves categories and tags</li> </ul> Step 3: Handle Images and Media</h2> WordPress stores images in wp-content/uploads/YEAR/MONTH/</code>. You need to: 1. Download all images: Use wget or a WordPress plugin to download your media library: wget -r -np -nH --cut-dirs=3 -R index.html \ https://yoursite.com/wp-content/uploads/ </code></pre> 2. Move to Zola's static directory: mv uploads static/images </code></pre> 3. Update image references: Your converted markdown will have references like: ![Alt text](https://yoursite.com/wp-content/uploads/2023/05/image.jpg) </code></pre> Update them to: ![Alt text](/images/2023/05/image.jpg) </code></pre> Use find and replace or a script: # In your content directory find . -name "*.md" -type f -exec sed -i \ 's|https://yoursite.com/wp-content/uploads|/images|g' {} + </code></pre> Step 4: Set Up Zola Structure</h2> Create your Zola site: zola init my-site cd my-site </code></pre> Move converted posts: mkdir -p content/blog mv ../converted-posts/*.md content/blog/ </code></pre> Create content/blog/_index.md</code>: +++ title = "Blog" sort_by = "date" template = "blog.html" page_template = "blog-page.html" paginate_by = 10 +++ </code></pre> Step 5: Handle URL Structure</h2> WordPress typically uses URLs like: yoursite.com/2023/05/post-title/</code></li> yoursite.com/category/tech/post-title/</code></li> </ul> Zola defaults to: yoursite.com/blog/post-title/</code></li> </ul> Option 1: Accept new URLs and set up redirects Create a _redirects</code> file for Netlify or use meta refresh in HTML: /2023/05/old-post-title/ /blog/old-post-title/ 301 </code></pre> Option 2: Match WordPress structure Configure Zola's config.toml</code>: [slugify] paths = "safe" taxonomies = "safe" # In your section front matter [extra] # You can customize paths per post </code></pre> Or in individual posts, set custom paths: +++ title = "My Post" date = 2023-05-15 path = "2023/05/my-post" +++ </code></pre> Step 6: Migrate Comments</h2> WordPress comments can't directly transfer to static sites. Options: 1. Use a third-party service: Disqus (free, but ads)</li> Utterances (GitHub-based, clean)</li> Commento (open-source, self-hostable)</li> </ul> 2. Export and display statically: Export comments from WordPress, convert to markdown, and display them as static content at the bottom of posts. 3. Disable comments: If comments weren't active or valuable, simply don't include them. I chose Utterances for its simplicity and GitHub integration. Step 7: Create Templates</h2> Build basic templates matching your WordPress design: Base template (templates/base.html</code>): <!DOCTYPE html> <html lang="en"> <head> <meta charset="UTF-8"> <title>{% block title %}{{ config.title }}{% endblock %}</title> <link rel="stylesheet" href="#"> </head> <body> <header> <nav> <a href="#">Home</a> <a href="#">Blog</a> </nav> </header> <main> {% block content %}{% endblock %} </main> </body> </html> </code></pre> Blog post template (templates/blog-page.html</code>): {% extends "base.html" %} {% block content %} <article> <h1>{{ page.title }}</h1> <time>{{ page.date | date(format="%B %d, %Y") }}</time> <div class="content"> {{ page.content | safe }} </div> {% if page.taxonomies.tags %} <div class="tags"> {% for tag in page.taxonomies.tags %} <a href="{{ get_taxonomy_url(kind="tags", name=tag) }}">#{{ tag }}</a> {% endfor %} </div> {% endif %} </article> {% endblock %} </code></pre> Step 8: Style Migration</h2> Export your WordPress CSS or recreate the design. If you used a theme, you might need to rebuild styles from scratch. Zola compiles Sass, so use that for organization: mkdir sass # Create sass/style.scss with your styles </code></pre> Step 9: Test Everything</h2> Before going live: Check all internal links: zola check </code></pre> </li> Verify images load: Look for broken image links</li> Ensure paths are correct</li> </ul> </li> Test on local server: zola serve </code></pre> </li> Review post formatting: Check markdown rendering</li> Verify code blocks</li> Test list formatting</li> </ul> </li> Validate RSS feed: Check public/rss.xml</code> after build</li> </ul> </li> </ol> Step 10: Deploy</h2> Build the site: zola build </code></pre> Deploy the public/</code> directory to: GitHub Pages (free)</li> Netlify (free, easy continuous deployment)</li> Cloudflare Pages (free, fast CDN)</li> Any static host</li> </ul> For Netlify, create netlify.toml</code>: [build] command = "zola build" publish = "public" [build.environment] ZOLA_VERSION = "0.18.0" [[redirects]] from = "/wp-content/uploads/*" to = "/images/:splat" status = 301 </code></pre> Post-Migration Checklist</h2> All posts migrated and rendering correctly</li> Images loading from new paths</li> RSS feed working</li> Internal links updated</li> URL redirects configured</li> Comments solution implemented (if wanted)</li> Analytics added (if needed)</li> Search functionality (if needed)</li> Domain pointed to new host</li> SSL certificate configured</li> Old WordPress site backed up before shutdown</li> </ul> What I Learned</h2> Week 1 after migration: Pages loaded 10x faster</li> No more plugin update anxiety</li> Editing in markdown felt liberating</li> Git history for all content was valuable</li> </ul> Month 1: Zero maintenance time spent</li> Hosting costs dropped to $0</li> Could work on posts offline</li> Deploy workflow became natural</li> </ul> Month 6: Never looked back</li> Writing more because the friction is gone</li> Site is still fast, no degradation</li> No security worries</li> </ul> Common Issues and Solutions</h2> Problem: HTML in converted markdown looks messy Solution: Clean up the markdown manually or improve your conversion script. Some HTML is fine—Zola renders it. Problem: WordPress shortcodes don't convert Solution: Replace WordPress shortcodes with equivalent HTML or Zola shortcodes. Create custom shortcodes for complex elements. Problem: Featured images missing Solution: WordPress featured images need special handling. Extract them from the XML and add to front matter: +++ [extra] featured_image = "/images/2023/05/featured.jpg" +++ </code></pre> Problem: Categories and tags not working Solution: Ensure taxonomies are configured in config.toml</code> and properly formatted in front matter. Is Migration Worth It?</h2> For me: absolutely. The trade-offs favor static generation when: Your site is mostly static content</li> You're comfortable with markdown and git</li> You want maximum performance</li> You want to minimize maintenance</li> Hosting costs matter</li> </ul> It's not worth it if: You need complex user interactions</li> Multiple non-technical people need to edit content</li> You heavily use WordPress-specific plugins</li> You're not comfortable with command-line tools</li> </ul> Resources That Helped</h2> Zola documentation (comprehensive)</li> html2text Python library (HTML to markdown conversion)</li> wordpress-export-to-markdown npm package</li> Utterances for comments</li> Netlify for hosting and deployment</li> </ul> The migration took one weekend of focused work. Six months later, I have zero regrets. The site is faster, cheaper to run, and more enjoyable to maintain. If your WordPress site is primarily a blog with static content, Zola is a compelling alternative.



How I Spent One Week with Zola
2025-11-20T00:00:00+00:00
I've been putting off rebuilding my blog for months. I knew I wanted to move away from my current setup, but every static site generator I looked at felt like it required too much overhead. Then I came across Zola, and something about the "single binary, zero dependencies" pitch made me curious enough to give it a real shot.</p>
I gave myself one week. Seven days to evaluate Zola, rebuild my site, and decide if this was the tool I'd been looking for. Here's what actually happened.</p>
Day 1: Setup and First Impressions</h2>
The installation was almost anticlimactic. Download a binary, add it to my PATH, run zola init</code>. No virtual environment, no npm install waiting for the progress bar, no dependency resolution. Just... done.</p>
I spent the rest of day one reading through the documentation and setting up the basic structure. The docs are well-organized and surprisingly concise. Within a few hours, I had a basic site running with zola serve</code>, and the live reload was noticeably fast. Not "fast enough" fast—actually fast.</p>
The Tera templating syntax felt immediately familiar. If you've used Jinja2 (and I have), you're basically already trained. I threw together a simple base template and a post layout, and I was rendering Markdown by evening.</p>
Day 1 verdict:</strong> This is refreshingly simple. Cautiously optimistic.</p>
Day 2: Content Migration and Structure</h2>
I spent day two migrating my existing blog posts and figuring out Zola's content model. This is where the opinionated structure became apparent.</p>
Zola wants you to organize content into sections. Each section is a directory with an _index.md</code> file. Pages are individual markdown files. It's more structured than just dumping markdown files wherever, but once I understood the pattern, it made sense.</p>
The front matter format was slightly different from what I was using before, so I wrote a quick script to convert my posts. Nothing complicated—mostly adjusting date formats and metadata fields.</p>
What surprised me was how fast Zola rebuilt the site even as I was adding more content. I'm used to SSGs slowing down as content grows. Zola just... didn't.</p>
Day 2 verdict:</strong> The opinionated structure takes some adjustment but pays off in clarity.</p>
Day 3: Multilingual Support</h2>
I needed my site to work in both English and Spanish. This is where I expected pain, because multilingual support is usually either an afterthought or a complex configuration nightmare.</p>
Zola's multilingual support is shockingly straightforward. You add default_language</code> to your config, define your languages, and create content with language codes in the filenames (like about.es.md</code>). That's it. Zola handles the routing and switching.</p>
I spent maybe two hours setting this up, including creating translated versions of my templates. The language switching just worked. No plugins, no complex routing rules, no confusion.</p>
Day 3 verdict:</strong> This is how multilingual support should work everywhere.</p>
Day 4: Building the Features I Actually Want</h2>
Day four was about building the features I actually needed: a featured posts section, proper pagination, tag pages, and RSS feeds.</p>
RSS was already built-in. Just enable it in the config. Done.</p>
Pagination is built-in. Add a few lines to your template. Done.</p>
Taxonomies (tags, categories) are first-class concepts. Configure them once, use them everywhere.</p>
The featured posts section required a bit more thought. I added a featured</code> field to my post front matter, then filtered posts in my template:</p>
{% set featured = section.pages | filter(attribute="extra.featured", value=true) %}
</span></code></pre>
Clean, readable, works perfectly. By the end of day four, my site had all the features I wanted, and I hadn't written any plugins or external scripts.</p>
Day 4 verdict:</strong> Built-in features cover 90% of what you actually need.</p>
Day 5: Styling with Sass</h2>
I don't love writing CSS, but I do like Sass for organization and variables. Zola compiles Sass out of the box.</p>
I created a sass</code> directory, wrote my styles with nesting and variables, and Zola just handled it. No webpack configuration, no additional dependencies, no build scripts. It compiled on save and the changes appeared immediately.</p>
This is where the "batteries included" philosophy really clicked. Every time I expected to need an extra tool or plugin, Zola already had it built-in.</p>
Day 5 verdict:</strong> The more I use Zola, the less I have to configure.</p>
Day 6: Polish and Refinements</h2>
Day six was cleanup: improving templates, adding proper metadata, testing the build on different content, and making sure everything worked correctly.</p>
I experimented with Zola's shortcodes for embedding content in Markdown. They're straightforward—define a template, call it from markdown. I built a couple for image galleries and code examples.</p>
I also tested the production build. The output is clean, minimal, and fast. Zola doesn't add unnecessary JavaScript or bloat. What you build is what you get.</p>
Day 6 verdict:</strong> The polish is in the details Zola got right.</p>
Day 7: Deployment and Reflection</h2>
The final day was about deployment. I pushed to GitHub, set up a simple GitHub Action that downloads Zola, builds the site, and deploys to GitHub Pages. The entire CI script is about 15 lines.</p>
No installing Node.js in CI, no pip installing dependencies, no caching layers to speed up repeated builds. Download one binary, run one command, deploy.</p>
As I looked at what I'd built in a week, I realized something: I'd spent most of my time building my site, not configuring my build tool. I wasn't debugging plugin conflicts or wrestling with complicated documentation. I was writing templates, styling pages, and migrating content.</p>
Day 7 verdict:</strong> This is what I've been looking for.</p>
What I Learned About Zola</h2>
The speed is real.</strong> It's not marketing. Rebuilds are genuinely fast enough that the feedback loop feels instant. This matters more than you'd think—it keeps you in flow instead of waiting.</p>
Batteries included works.</strong> I'm used to static site generators being minimal cores that you extend with plugins. Zola's approach of including everything is different, but it's efficient. I never had to evaluate plugins or worry about compatibility.</p>
Opinionated structure helps.</strong> At first, Zola's structured content model felt restrictive. By day three, I appreciated it. The constraints make things predictable, and predictable means less time deciding how to organize things.</p>
Tera is excellent.</strong> The templating is powerful enough for anything I needed but simple enough to read six months from now. The Jinja2 inspiration was the right call.</p>
Zero dependencies isn't just a feature—it's a philosophy.</strong> Not managing Python versions, npm packages, or virtual environments removed an entire category of problems. My project is my content and my templates. That's it.</p>
What I Missed (Briefly)</h2>
The plugin ecosystem. When I wanted something custom, I had to build it in templates rather than reaching for a plugin. This was actually fine—Tera is capable enough—but there were moments where I wished for a Python script or npm package.</p>
The theme ecosystem is smaller. I built my own design, which I wanted to do anyway, but if you're hoping to grab a polished theme and go, options are limited.</p>
The Verdict</h2>
Seven days in, I'm keeping Zola.</p>
This isn't because Zola does things other static site generators can't—it's because Zola does fewer things but does them with less friction. The simplicity isn't simplistic; it's intentional.</p>
I came in skeptical that a tool could be both powerful and simple. Zola proved me wrong by being opinionated about the right things and flexible about everything else.</p>
My blog is live, builds are fast, development is pleasant, and I have zero dependencies to maintain. If that sounds appealing, give Zola a week. You might be surprised how much you can build when the tool gets out of your way.</p>
Resources That Helped</h2>

The official Zola documentation (start here)</li>
The Tera template documentation (for advanced templating)</li>
Zola's GitHub discussions (helpful community)</li>
Example sites in Zola's showcase (seeing real implementations helps)</li>
</ul>
Would I recommend Zola? If you want simplicity, speed, and don't need extensive plugin ecosystems, absolutely. If you need complex Python integrations or want thousands of themes to choose from, look elsewhere.</p>
For me, Zola hit the sweet spot: powerful enough for what I need, simple enough to stay out of my way. One week was enough to be convinced.</p>


Creating a Blog with Zola: A Practical Guide
2025-11-19T00:00:00+00:00
Building a blog with Zola is straightforward, but there are patterns and decisions that aren't immediately obvious from the documentation. This guide walks through creating a real blog, covering the practical choices you'll face and the solutions that work well.</p>
Getting Started: Installation and Project Setup</h2>
First, install Zola. Download the binary for your platform from the releases page, or use a package manager:</p>
# macOS
</span>brew</span> install zola
</span>
</span># Linux
</span>snap</span> install zola</span> --edge
</span>
</span># Or download the binary directly
</span></code></pre>
Create your project:</p>
zola</span> init my-blog
</span>cd</span> my-blog
</span></code></pre>
Zola will ask a few questions. For a blog, answer:</p>

URL: Your production URL (you can change this later)</li>
Sass compilation: Yes</li>
Syntax highlighting: Yes</li>
</ul>
Your directory structure looks like this:</p>
my-blog/
</span>├── config.toml
</span>├── content/
</span>├── sass/
</span>├── static/
</span>├── templates/
</span>└── themes/
</span></code></pre>
Configuration: The Foundation</h2>
Open config.toml</code> and configure the essentials:</p>
base_url </span>= "</span>https://yourdomain.com</span>"
</span>title </span>= "</span>Your Blog Name</span>"
</span>description </span>= "</span>A brief description of your blog</span>"
</span>
</span># Compile Sass files
</span>compile_sass </span>= </span>true
</span>
</span># Enable syntax highlighting for code blocks
</span>highlight_code </span>= </span>true
</span>highlight_theme </span>= "</span>base16-ocean-dark</span>"
</span>
</span># Generate RSS feed
</span>generate_feed </span>= </span>true
</span>feed_filename </span>= "</span>rss.xml</span>"
</span>
</span># Taxonomies (tags and categories)
</span>taxonomies </span>= [
</span>    {</span>name </span>= "</span>tags</span>", </span>feed </span>= </span>true</span>},
</span>    {</span>name </span>= "</span>categories</span>", </span>feed </span>= </span>true</span>},
</span>]
</span>
</span>[markdown]
</span># Enable smart punctuation and other features
</span>smart_punctuation </span>= </span>true
</span>highlight_code </span>= </span>true
</span>
</span>[extra]
</span># Add any custom variables you need
</span>author </span>= "</span>Your Name</span>"
</span>github </span>= "</span>https://github.com/yourusername</span>"
</span>twitter </span>= "</span>yourusername</span>"
</span></code></pre>
This configuration gives you a solid foundation: RSS feeds, taxonomies for organizing content, and code highlighting.</p>
Content Structure: Organizing Your Posts</h2>
Create a blog section in content/blog/</code>:</p>
mkdir -p</span> content/blog
</span></code></pre>
Create content/blog/_index.md</code>:</p>
+++
</span>title = "Blog"
</span>sort_by = "date"
</span>template = "blog.html"
</span>page_template = "blog-page.html"
</span>paginate_by = 10
</span>+++
</span>
</span>Welcome to my blog where I write about web development, programming, and technology.
</span></code></pre>
This file defines how the blog section behaves:</p>

sort_by = "date"</code> orders posts by publication date</li>
paginate_by = 10</code> creates pagination every 10 posts</li>
template</code> defines the list view</li>
page_template</code> defines individual post view</li>
</ul>
Creating Your First Post</h2>
Create content/blog/hello-world.md</code>:</p>
+++
</span>title = "Hello World: Starting a New Blog"
</span>date = 2025-11-16
</span>description = "My first post on this new blog built with Zola"
</span>[taxonomies]
</span>tags = ["meta", "blogging"]
</span>categories = ["General"]
</span>
</span>[extra]
</span>featured = true
</span>+++
</span>
</span>Welcome to my blog! This is my first post built with Zola, and I'm excited to share what I'm learning.
</span>
</span><!-- more -->
</span>
</span>## Why Zola?
</span>
</span>I chose Zola for several reasons:
</span>- Fast builds
</span>- Zero dependencies
</span>- Simple configuration
</span>- Great multilingual support
</span>
</span>## What's Next?
</span>
</span>I plan to write about web development, share tutorials, and document my learning journey.
</span>
</span>Stay tuned for more content!
</span></code></pre>
The <!-- more --></code> tag creates a summary break. Text before it appears in post previews.</p>
Templates: Building the Blog Layout</h2>
Create templates/base.html</code> as your foundation:</p>
<!</span>DOCTYPE </span>html</span>>
</span><</span>html </span>lang</span>="</span>{{ lang | default(value=</span>"</span>en</span>"</span>) }}</span>"</span>>
</span><</span>head</span>>
</span>    <</span>meta </span>charset</span>="</span>UTF-8</span>">
</span>    <</span>meta </span>name</span>="</span>viewport</span>" </span>content</span>="</span>width=device-width, initial-scale=1.0</span>">
</span>    <</span>title</span>>{% block title %}{{ config.title }}{% endblock %}</</span>title</span>>
</span>    <</span>meta </span>name</span>="</span>description</span>" </span>content</span>="</span>{% block description %}{{ config.description }}{% endblock %}</span>">
</span>    
</span>    {% if config.generate_feed %}
</span>    <</span>link </span>rel</span>="</span>alternate</span>" </span>type</span>="</span>application/rss+xml</span>" </span>title</span>="</span>RSS</span>" </span>href</span>="</span>#</span>">
</span>    {% endif %}
</span>    
</span>    <</span>link </span>rel</span>="</span>/</span>">
</span></</span>head</span>>
</span><</span>body</span>>
</span>    <</span>header</span>>
</span>        <</span>nav</span>>
</span>            <</span>a </span>href</span>="</span>#</span>">{{ config.title }}</</span>a</span>>
</span>            <</span>a </span>href</span>="</span>#</span>">Blog</</span>a</span>>
</span>            <</span>a </span>href</span>="</span>#</span>">About</</span>a</span>>
</span>        </</span>nav</span>>
</span>    </</span>header</span>>
</span>    
</span>    <</span>main</span>>
</span>        {% block content %}{% endblock %}
</span>    </</span>main</span>>
</span>    
</span>    <</span>footer</span>>
</span>        <</span>p</span>></span>&</span>copy;</span> {{ now() | date(format="%Y") }} {{ config.extra.author }}</</span>p</span>>
</span>    </</span>footer</span>>
</span></</span>body</span>>
</span></</span>html</span>>
</span></code></pre>
Create templates/blog.html</code> for the blog list:</p>
{% extends "base.html" %}
</span>
</span>{% block title %}{{ section.title }} | {{ config.title }}{% endblock %}
</span>{% block description %}{{ section.description | default(value=config.description) }}{% endblock %}
</span>
</span>{% block content %}
</span><</span>div </span>class</span>="</span>blog-list</span>">
</span>    <</span>h1</span>>{{ section.title }}</</span>h1</span>>
</span>    
</span>    {{ section.content | safe }}
</span>    
</span>    {% if section.pages %}
</span>    <</span>div </span>class</span>="</span>posts</span>">
</span>        {% for page in section.pages %}
</span>        <</span>article </span>class</span>="</span>post-preview</span>">
</span>            <</span>h2</span>><</span>a </span>href</span>="</span>{{ page.permalink }}</span>">{{ page.title }}</</span>a</span>></</span>h2</span>>
</span>            <</span>time </span>datetime</span>="</span>{{ page.date }}</span>">{{ page.date | date(format="%B %d, %Y") }}</</span>time</span>>
</span>            
</span>            {% if page.summary %}
</span>            <</span>p</span>>{{ page.summary | safe }}</</span>p</span>>
</span>            {% elif page.description %}
</span>            <</span>p</span>>{{ page.description }}</</span>p</span>>
</span>            {% endif %}
</span>            
</span>            {% if page.taxonomies.tags %}
</span>            <</span>div </span>class</span>="</span>tags</span>">
</span>                {% for tag in page.taxonomies.tags %}
</span>                <</span>a </span>href</span>="</span>{{ get_taxonomy_url(kind=</span>"</span>tags</span>"</span>, name</span>=</span>tag) </span>}}</span>"</span>>#{{ tag }}</</span>a</span>>
</span>                {% endfor %}
</span>            </</span>div</span>>
</span>            {% endif %}
</span>            
</span>            <</span>a </span>href</span>="</span>{{ page.permalink }}</span>">Read more →</</span>a</span>>
</span>        </</span>article</span>>
</span>        {% endfor %}
</span>    </</span>div</span>>
</span>    {% endif %}
</span>    
</span>    {% if paginator %}
</span>    <</span>nav </span>class</span>="</span>pagination</span>">
</span>        {% if paginator.previous %}
</span>        <</span>a </span>href</span>="</span>{{ paginator.previous }}</span>">← Newer</</span>a</span>>
</span>        {% endif %}
</span>        
</span>        <</span>span</span>>Page {{ paginator.current_index }} of {{ paginator.number_pagers }}</</span>span</span>>
</span>        
</span>        {% if paginator.next %}
</span>        <</span>a </span>href</span>="</span>{{ paginator.next }}</span>">Older →</</span>a</span>>
</span>        {% endif %}
</span>    </</span>nav</span>>
</span>    {% endif %}
</span></</span>div</span>>
</span>{% endblock %}
</span></code></pre>
Create templates/blog-page.html</code> for individual posts:</p>
{% extends "base.html" %}
</span>
</span>{% block title %}{{ page.title }} | {{ config.title }}{% endblock %}
</span>{% block description %}{{ page.description | default(value=page.summary) }}{% endblock %}
</span>
</span>{% block content %}
</span><</span>article </span>class</span>="</span>blog-post</span>">
</span>    <</span>header</span>>
</span>        <</span>h1</span>>{{ page.title }}</</span>h1</span>>
</span>        <</span>div </span>class</span>="</span>post-meta</span>">
</span>            <</span>time </span>datetime</span>="</span>{{ page.date }}</span>">{{ page.date | date(format="%B %d, %Y") }}</</span>time</span>>
</span>            {% if page.extra.reading_time %}
</span>            <</span>span</span>>• {{ page.reading_time }} min read</</span>span</span>>
</span>            {% endif %}
</span>        </</span>div</span>>
</span>        
</span>        {% if page.taxonomies.tags %}
</span>        <</span>div </span>class</span>="</span>tags</span>">
</span>            {% for tag in page.taxonomies.tags %}
</span>            <</span>a </span>href</span>="</span>{{ get_taxonomy_url(kind=</span>"</span>tags</span>"</span>, name</span>=</span>tag) </span>}}</span>"</span>>#{{ tag }}</</span>a</span>>
</span>            {% endfor %}
</span>        </</span>div</span>>
</span>        {% endif %}
</span>    </</span>header</span>>
</span>    
</span>    <</span>div </span>class</span>="</span>post-content</span>">
</span>        {{ page.content | safe }}
</span>    </</span>div</span>>
</span>    
</span>    {% if page.earlier or page.later %}
</span>    <</span>nav </span>class</span>="</span>post-navigation</span>">
</span>        {% if page.earlier %}
</span>        <</span>a </span>href</span>="</span>{{ page.earlier.permalink }}</span>" </span>class</span>="</span>prev</span>">← {{ page.earlier.title }}</</span>a</span>>
</span>        {% endif %}
</span>        {% if page.later %}
</span>        <</span>a </span>href</span>="</span>{{ page.later.permalink }}</span>" </span>class</span>="</span>next</span>">{{ page.later.title }} →</</span>a</span>>
</span>        {% endif %}
</span>    </</span>nav</span>>
</span>    {% endif %}
</span></</span>article</span>>
</span>{% endblock %}
</span></code></pre>
Styling with Sass</h2>
Create sass/style.scss</code>:</p>
// Variables
</span>$</span>primary-color</span>: </span>#2563eb</span>;
</span>$</span>text-color</span>: </span>#1f2937</span>;
</span>$</span>background</span>: </span>#ffffff</span>;
</span>$</span>border-color</span>: </span>#e5e7eb</span>;
</span>$</span>max-width</span>: </span>800px</span>;
</span>
</span>// Base styles
</span>* </span>{
</span>    margin: </span>0</span>;
</span>    padding: </span>0</span>;
</span>    box-sizing: border-box;
</span>}
</span>
</span>body </span>{
</span>    font-family: system-ui, </span>-apple-system</span>, sans-serif;
</span>    line-height: </span>1.6</span>;
</span>    color: $</span>text-color</span>;
</span>    background: $</span>background</span>;
</span>}
</span>
</span>// Layout
</span>header </span>{
</span>    border-bottom: </span>1px </span>solid $</span>border-color</span>;
</span>    padding: </span>1rem 0</span>;
</span>    
</span>    </span>nav </span>{
</span>        max-width: $</span>max-width</span>;
</span>        margin: </span>0 </span>auto;
</span>        padding: </span>0 1rem</span>;
</span>        display: flex;
</span>        gap: </span>2rem</span>;
</span>        
</span>        </span>a </span>{
</span>            text-decoration: none;
</span>            color: $</span>text-color</span>;
</span>            font-weight: </span>500</span>;
</span>            
</span>            </span>&</span>:</span>hover </span>{
</span>                color: $</span>primary-color</span>;
</span>            }
</span>            
</span>            </span>&</span>:</span>first-child </span>{
</span>                font-weight: </span>700</span>;
</span>                margin-right: auto;
</span>            }
</span>        }
</span>    }
</span>}
</span>
</span>main </span>{
</span>    max-width: $</span>max-width</span>;
</span>    margin: </span>2rem </span>auto;
</span>    padding: </span>0 1rem</span>;
</span>}
</span>
</span>footer </span>{
</span>    border-top: </span>1px </span>solid $</span>border-color</span>;
</span>    padding: </span>2rem 1rem</span>;
</span>    text-align: center;
</span>    color: </span>#6b7280</span>;
</span>    margin-top: </span>4rem</span>;
</span>}
</span>
</span>// Blog styles
</span>.</span>post-preview </span>{
</span>    margin-bottom: </span>3rem</span>;
</span>    
</span>    </span>h2 </span>{
</span>        margin-bottom: </span>0.5rem</span>;
</span>        
</span>        </span>a </span>{
</span>            color: $</span>text-color</span>;
</span>            text-decoration: none;
</span>            
</span>            </span>&</span>:</span>hover </span>{
</span>                color: $</span>primary-color</span>;
</span>            }
</span>        }
</span>    }
</span>    
</span>    </span>time </span>{
</span>        color: </span>#6b7280</span>;
</span>        font-size: </span>0.9rem</span>;
</span>    }
</span>    
</span>    </span>p </span>{
</span>        margin: </span>1rem 0</span>;
</span>    }
</span>}
</span>
</span>.</span>blog-post </span>{
</span>    </span>.</span>post-content </span>{
</span>        margin: </span>2rem 0</span>;
</span>        
</span>        </span>h2</span>, </span>h3 </span>{
</span>            margin: </span>2rem 0 1rem</span>;
</span>        }
</span>        
</span>        </span>p </span>{
</span>            margin: </span>1rem 0</span>;
</span>        }
</span>        
</span>        </span>code </span>{
</span>            background: </span>#f3f4f6</span>;
</span>            padding: </span>0.2rem 0.4rem</span>;
</span>            border-radius: </span>3px</span>;
</span>            font-size: </span>0.9em</span>;
</span>        }
</span>        
</span>        </span>pre </span>{
</span>            background: </span>#1f2937</span>;
</span>            color: </span>#f3f4f6</span>;
</span>            padding: </span>1rem</span>;
</span>            border-radius: </span>5px</span>;
</span>            overflow-x: auto;
</span>            
</span>            </span>code </span>{
</span>                background: none;
</span>                padding: </span>0</span>;
</span>            }
</span>        }
</span>    }
</span>}
</span>
</span>.</span>tags </span>{
</span>    display: flex;
</span>    gap: </span>0.5rem</span>;
</span>    flex-wrap: wrap;
</span>    margin: </span>1rem 0</span>;
</span>    
</span>    </span>a </span>{
</span>        background: </span>#f3f4f6</span>;
</span>        padding: </span>0.25rem 0.75rem</span>;
</span>        border-radius: </span>3px</span>;
</span>        text-decoration: none;
</span>        color: $</span>text-color</span>;
</span>        font-size: </span>0.9rem</span>;
</span>        
</span>        </span>&</span>:</span>hover </span>{
</span>            background: $</span>primary-color</span>;
</span>            color: white;
</span>        }
</span>    }
</span>}
</span>
</span>.</span>pagination </span>{
</span>    display: flex;
</span>    justify-content: space-between;
</span>    align-items: center;
</span>    margin: </span>3rem 0</span>;
</span>    padding: </span>1rem 0</span>;
</span>    border-top: </span>1px </span>solid $</span>border-color</span>;
</span>}
</span>
</span>// Responsive
</span>@media </span>(max-width: </span>768px</span>) {
</span>    </span>header nav </span>{
</span>        flex-direction: column;
</span>        gap: </span>1rem</span>;
</span>    }
</span>}
</span></code></pre>
Adding Homepage</h2>
Create content/_index.md</code>:</p>
+++
</span>title = "Home"
</span>template = "index.html"
</span>+++
</span></code></pre>
Create templates/index.html</code>:</p>
{% extends "base.html" %}
</span>
</span>{% block content %}
</span><</span>div </span>class</span>="</span>home</span>">
</span>    <</span>h1</span>>Welcome to {{ config.title }}</</span>h1</span>>
</span>    <</span>p </span>class</span>="</span>intro</span>">{{ config.description }}</</span>p</span>>
</span>    
</span>    {% set blog_section = get_section(path="blog/_index.md") %}
</span>    {% if blog_section.pages %}
</span>    <</span>section </span>class</span>="</span>recent-posts</span>">
</span>        <</span>h2</span>>Recent Posts</</span>h2</span>>
</span>        <</span>div </span>class</span>="</span>posts</span>">
</span>            {% for page in blog_section.pages | slice(end=5) %}
</span>            <</span>article </span>class</span>="</span>post-preview</span>">
</span>                <</span>h3</span>><</span>a </span>href</span>="</span>{{ page.permalink }}</span>">{{ page.title }}</</span>a</span>></</span>h3</span>>
</span>                <</span>time </span>datetime</span>="</span>{{ page.date }}</span>">{{ page.date | date(format="%B %d, %Y") }}</</span>time</span>>
</span>                {% if page.description %}
</span>                <</span>p</span>>{{ page.description }}</</span>p</span>>
</span>                {% endif %}
</span>            </</span>article</span>>
</span>            {% endfor %}
</span>        </</span>div</span>>
</span>        <</span>a </span>href</span>="</span>#</span>" </span>class</span>="</span>view-all</span>">View all posts →</</span>a</span>>
</span>    </</span>section</span>>
</span>    {% endif %}
</span></</span>div</span>>
</span>{% endblock %}
</span></code></pre>
Running Your Blog</h2>
Start the development server:</p>
zola</span> serve
</span></code></pre>
Visit http://127.0.0.1:1111</code> to see your blog. Changes to content and templates reload automatically.</p>
Building for Production</h2>
Build your site for deployment:</p>
zola</span> build
</span></code></pre>
The static site is generated in the public/</code> directory. Upload these files to any static hosting service.</p>
Deployment to GitHub Pages</h2>
Create .github/workflows/deploy.yml</code>:</p>
name</span>: </span>Deploy to GitHub Pages
</span>
</span>on</span>:
</span>  </span>push</span>:
</span>    </span>branches</span>: [</span>main</span>]
</span>
</span>jobs</span>:
</span>  </span>build</span>:
</span>    </span>runs-on</span>: </span>ubuntu-latest
</span>    </span>steps</span>:
</span>      - </span>uses</span>: </span>actions/checkout@v2
</span>      
</span>      - </span>name</span>: </span>Install Zola
</span>        </span>run</span>: </span>|
</span>          wget https://github.com/getzola/zola/releases/download/v0.18.0/zola-v0.18.0-x86_64-unknown-linux-gnu.tar.gz
</span>          tar xzf zola-v0.18.0-x86_64-unknown-linux-gnu.tar.gz
</span>          sudo mv zola /usr/local/bin/
</span>      
</span>      - </span>name</span>: </span>Build
</span>        </span>run</span>: </span>zola build
</span>      
</span>      - </span>name</span>: </span>Deploy
</span>        </span>uses</span>: </span>peaceiris/actions-gh-pages@v3
</span>        </span>with</span>:
</span>          </span>github_token</span>: </span>${{ secrets.GITHUB_TOKEN }}
</span>          </span>publish_dir</span>: </span>./public
</span></code></pre>
Push to GitHub, enable GitHub Pages in your repository settings, and your blog deploys automatically on every push.</p>
Next Steps</h2>
Your blog is now functional. Consider adding:</p>
Featured posts</strong>: Add a featured</code> field to front matter and filter in templates
Reading time</strong>: Use {{ page.reading_time }}</code> to show estimated reading time
Table of contents</strong>: Enable insert_anchor_links = "left"</code> in config for heading anchors
Search</strong>: Implement search with Zola's search index feature
Comments</strong>: Integrate a commenting system like utterances or Disqus
Analytics</strong>: Add analytics with a simple script include</p>
Key Takeaways</h2>
Creating a blog with Zola is refreshingly straightforward:</p>

Content is just Markdown</strong> with front matter—no complex APIs or abstractions</li>
Templates are Tera</strong>—if you know Jinja2, you already know 90% of what you need</li>
Built-in features eliminate plugins</strong>—Sass, syntax highlighting, RSS, and taxonomies work out of the box</li>
Fast iteration</strong>—changes appear instantly during development</li>
Simple deployment</strong>—static files can be hosted anywhere</li>
</ol>
The key to productive Zola development is embracing its opinions. The structure might feel restrictive at first, but it eliminates decision fatigue and lets you focus on content.</p>
Start simple, write content, and expand as you need more features. Zola gets out of your way and lets you build.</p>


Why Zola Might Be Your Next Static Site Generator
2025-11-16T00:00:00+00:00
If you're in the market for a static site generator, you've probably encountered the usual suspects: Hugo, Jekyll, Gatsby, Astro. But there's a compelling alternative that deserves your attention: Zola.</p>
What Makes Zola Different</h2>
Zola is a static site generator built in Rust, which immediately gives it two advantages: blazing speed and zero dependencies. Unlike Jekyll (which requires Ruby) or Hugo (which needs Go), Zola is distributed as a single binary. Download it, and you're ready to build.</p>
This simplicity extends to the entire development experience. While other generators require you to manage plugin ecosystems and dependency chains, Zola ships with everything built-in: Sass compilation, syntax highlighting, image processing, and a powerful templating engine called Tera.</p>
Built for Developers Who Value Speed</h2>
The performance is noticeable. Zola rebuilds sites almost instantaneously, making the local development experience smooth and interruption-free. The live reload is fast enough that you can see changes as you type.</p>
But speed isn't just about build times. Zola's approach to content organization is straightforward: sections, pages, and taxonomies. There's no complex abstraction layer to learn. If you understand how your content should be structured, you can map it directly to Zola's concepts.</p>
Where Zola Shines</h2>
Multilingual support is first-class in Zola, not an afterthought. You can create content in multiple languages without wrestling with plugins or custom configurations. The documentation is clear, and the patterns are consistent.</p>
The templating system, Tera, strikes a good balance between power and simplicity. It's Jinja2-inspired, so if you've worked with Python or Ansible, you'll feel at home. Macros, filters, and template inheritance work as you'd expect.</p>
The Trade-offs</h2>
Zola's ecosystem is smaller than Hugo's or Gatsby's. You won't find thousands of themes or plugins. This is both a constraint and a feature—it pushes you to build exactly what you need rather than cobbling together plugins that might conflict.</p>
The documentation is generally solid, though some advanced use cases require digging into GitHub issues or the community forum. The project is actively maintained, but it's a smaller team compared to other generators.</p>
Is Zola Right for You?</h2>
If you value simplicity, speed, and a single-binary distribution over a massive ecosystem, Zola is worth trying. It's particularly well-suited for blogs, documentation sites, and portfolios where you want full control without complexity.</p>
The learning curve is gentle, the builds are fast, and you'll spend more time writing content than configuring your build pipeline. Sometimes that's exactly what you need.</p>


Zola vs Astro: Traditional SSG Meets Modern JavaScript
2025-11-15T00:00:00+00:00
At first glance, comparing Zola and Astro might seem odd. One is a traditional static site generator built in Rust. The other is a modern JavaScript framework with an islands architecture. But both excel at building fast static sites, and both claim to make the process simpler. The question is: which kind of simplicity do you need?</p>
Philosophy: Everything Included vs Bring Your Own</h2>
Zola ships as a single binary with everything built-in. Download one file, and you have templating, Sass compilation, syntax highlighting, image processing, and live reload. No npm, no node_modules, no build configuration.</p>
Astro is a JavaScript framework that embraces the npm ecosystem. You install it via npm, configure it through JavaScript, and extend it with integrations. Want to use React components? Install the React integration. Need Tailwind? Add it. The philosophy is composition over inclusion.</p>
This isn't a value judgment—it's a fundamental difference in approach. Zola says "here's everything you need." Astro says "here's a foundation, add what you want."</p>
Installation and Setup</h2>
Getting started with Zola:</p>
# Download binary
</span># Add to PATH
</span>zola</span> init my-site
</span>zola</span> serve
</span></code></pre>
Getting started with Astro:</p>
npm</span> create astro@latest
</span># Answer interactive prompts
</span>npm</span> run dev
</span></code></pre>
Zola's approach means no node_modules folder, no package.json, no dependency updates. Your project is just your content and templates.</p>
Astro's approach means you're in the JavaScript ecosystem with all its benefits and complexities. You get access to npm packages, but you also manage dependencies.</p>
Component Model: Templates vs JavaScript Components</h2>
Zola uses Tera templates. You write HTML with template syntax for loops, conditionals, and macros. It's server-side templating—what you write is what gets rendered to HTML.</p>
Astro lets you write components in Astro syntax (which looks like JSX) and can integrate React, Vue, Svelte, or Solid components. You can mix and match frameworks in the same project. This is powerful if you want to reuse existing components or prefer a component-driven architecture.</p>
Here's the trade-off: Zola's templates are simpler but less powerful for interactive components. Astro's components are more complex but give you the full JavaScript ecosystem.</p>
Content Management</h2>
Both use Markdown for content, but they handle it differently.</p>
Zola has a structured content model with sections and pages. Front matter is strict but predictable. You organize content by directories, and Zola automatically generates routes. It's opinionated about structure, which reduces decisions.</p>
Astro is more flexible. You can put Markdown files anywhere, use content collections for structured data, or pull content from CMSs or APIs at build time. This flexibility is useful for complex sites but requires more decision-making.</p>
Performance: Both Fast, Different Reasons</h2>
Zola is fast because it's Rust. Build times are measured in milliseconds. It rebuilds incrementally during development, and changes appear nearly instantly.</p>
Astro is fast because it ships zero JavaScript by default. Your site is pure HTML and CSS unless you opt into client-side interactivity. When you do add JavaScript, Astro's islands architecture only hydrates the components that need it.</p>
In practice, both produce fast sites. Zola achieves this through traditional static generation. Astro achieves it through clever JavaScript optimization.</p>
Interactivity and JavaScript</h2>
This is where the paths diverge significantly.</p>
Zola doesn't have a story for complex client-side interactivity. You can add vanilla JavaScript, but if you need a React component or Vue widget, you're integrating it manually. Zola excels at static, content-focused sites.</p>
Astro was built for partial hydration. You can have an entirely static blog post with one interactive widget that loads React only for that component. This is Astro's killer feature—progressive enhancement through islands architecture.</p>
If your site is mostly static with occasional interactivity, Astro gives you a clear path forward. If your site is entirely static, Zola's simplicity might be preferable.</p>
Styling and Assets</h2>
Zola has built-in Sass compilation. Write .scss</code> files, and Zola handles them. For other assets, you put them in the static folder, and they're copied as-is.</p>
Astro integrates with modern tooling. You can use Tailwind, CSS-in-JS, CSS Modules, or whatever the JavaScript ecosystem offers. Asset optimization happens through Vite, Astro's build tool.</p>
Zola's approach is simpler but more limited. Astro's approach gives you more options but requires configuration.</p>
Ecosystem and Integrations</h2>
Zola's ecosystem is minimal. There are some themes and a small community. You're mostly building from scratch or adapting existing HTML/CSS templates.</p>
Astro's ecosystem is growing rapidly. There are integrations for CMSs, image optimization, analytics, and more. You can use any npm package. The community is active, and new integrations appear regularly.</p>
If you want to integrate with modern web development tools—TypeScript, Tailwind, MDX, image optimization, analytics—Astro makes this straightforward. With Zola, you're on your own.</p>
Multilingual Sites</h2>
Zola has first-class multilingual support. Create content in multiple languages, and Zola handles routing and structure automatically. It's straightforward and requires minimal configuration.</p>
Astro supports multilingual sites through routing configuration and content collections. It's more manual but also more flexible. You control exactly how languages are handled.</p>
Learning Curve</h2>
Zola's learning curve is gentle if you know HTML and are comfortable with template syntax. There's one templating language to learn (Tera), and the mental model is simple: templates render content to HTML.</p>
Astro's learning curve depends on your JavaScript experience. If you're comfortable with modern JavaScript, JSX, and component thinking, Astro feels natural. If you're new to this ecosystem, there's more to learn: component syntax, props, islands, integrations.</p>
Developer Experience</h2>
Zola's DX is about simplicity. Fast builds, simple mental model, no toolchain configuration. You focus on content and templates. The live reload is nearly instant.</p>
Astro's DX is about power and flexibility. You get TypeScript support, component frameworks, modern tooling, and extensive integrations. The development server is fast, and error messages are helpful.</p>
When to Choose Astro</h2>
Pick Astro if you:</p>

Need to mix static content with interactive components</li>
Want to use React, Vue, or Svelte components</li>
Need integration with modern JavaScript tooling</li>
Plan to pull content from APIs or CMSs</li>
Want TypeScript support out of the box</li>
Need to progressively enhance static pages with interactivity</li>
Are comfortable with npm and JavaScript tooling</li>
</ul>
When to Choose Zola</h2>
Pick Zola if you:</p>

Want zero dependency installation and maintenance</li>
Are building a content-focused site (blog, docs, portfolio)</li>
Prefer simplicity over flexibility</li>
Don't need complex client-side interactivity</li>
Want built-in Sass without configuration</li>
Value fast builds with minimal tooling</li>
Prefer a single binary over a JavaScript toolchain</li>
</ul>
The Real Decision Point</h2>
The choice between Zola and Astro isn't about which is better—it's about which model fits your project and preferences.</p>
Choose based on your site's needs:</p>

Pure static content with minimal interactivity? Zola's simplicity shines.</li>
Mix of static content and interactive components? Astro's islands architecture is perfect.</li>
Want to avoid JavaScript tooling entirely? Zola gives you that.</li>
Need the JavaScript ecosystem and its packages? Astro provides access.</li>
</ul>
Both will give you fast, performant sites. Zola does it with traditional static generation and zero dependencies. Astro does it with modern JavaScript tooling and optional interactivity.</p>
Neither is wrong. Pick the one that matches how you want to work, not just what you want to build.</p>


Zola vs Hugo: Choosing Between Two Speed Demons
2025-11-14T00:00:00+00:00
When you're picking a static site generator and performance matters, the conversation usually narrows down to two contenders: Hugo and Zola. Both are exceptionally fast, both compile to single binaries, and both can handle large sites without breaking a sweat. So how do you choose?</p>
The Single Binary Promise</h2>
Let's start with what they share: neither Hugo nor Zola requires you to install a language runtime. No npm, no Ruby gems, no Python virtual environments. You download a binary, add it to your path, and you're building sites. This is a massive advantage over Jekyll or Gatsby.</p>
Hugo is written in Go. Zola is written in Rust. From a user perspective, this distinction rarely matters, except that Rust's reputation for safety means Zola crashes are exceptionally rare—though to be fair, Hugo is rock-solid too.</p>
Build Speed: Both Winners</h2>
The truth? Both are absurdly fast. Hugo claims to build sites in milliseconds. Zola does the same. For most projects under a few thousand pages, the difference is imperceptible. You'll spend more time waiting for your browser to refresh than for either tool to rebuild.</p>
Where they diverge is in what comes next. Hugo's speed has led to massive sites—think 50,000+ pages. Zola is fast enough for most use cases, but it hasn't been battle-tested at that scale the same way Hugo has.</p>
Ecosystem: Size vs Simplicity</h2>
Hugo wins on ecosystem size, and it's not close. There are hundreds of themes, extensive documentation, and a large community. If you're building a documentation site, Hugo's ecosystem has mature solutions ready to use.</p>
Zola's ecosystem is deliberately smaller. There are fewer themes, fewer plugins, and a smaller community. This sounds like a disadvantage until you realize it's also freeing. You're not sifting through outdated themes or debugging plugin conflicts. You build what you need.</p>
The question is: do you want a marketplace or a workshop?</p>
Templating: Go Templates vs Tera</h2>
Hugo uses Go's template language. It's powerful but has a learning curve, especially if you're not familiar with Go. The syntax can feel verbose, and some operations that seem simple require looking up documentation.</p>
Zola uses Tera, which is based on Jinja2. If you've worked with Python, Django, or even Ansible, you'll recognize the patterns immediately. Filters, macros, and template inheritance work intuitively. The syntax is cleaner and more consistent.</p>
This is subjective, but for most developers, Tera is easier to pick up and more pleasant to work with.</p>
Content Organization</h2>
Hugo gives you tremendous flexibility in how you organize content. You can create custom content types, define complex taxonomies, and build intricate site structures. This power comes with complexity—Hugo's content model has more concepts to learn.</p>
Zola is more opinionated. You have sections, pages, and taxonomies. It's simpler but less flexible. For blogs, documentation, and portfolios, this simplicity is usually an advantage. For complex sites with unusual structures, Hugo's flexibility might be necessary.</p>
Multilingual Support</h2>
Both support multiple languages, but they approach it differently.</p>
Hugo has mature multilingual support with extensive configuration options. You can fine-tune how languages are handled, create language-specific menus, and manage translations with precision. It's comprehensive but requires more setup.</p>
Zola's multilingual support is straightforward and built-in. You create content in different languages, and Zola handles the routing. It's less configurable but requires almost no setup. For most multilingual sites, Zola's approach is sufficient and much simpler.</p>
Built-in Features vs Extensibility</h2>
Zola ships with Sass compilation, syntax highlighting, and image processing out of the box. You don't install plugins for these features—they're just there.</p>
Hugo requires external tools for some of these tasks or uses Hugo Pipes and Hugo Modules. It's more modular, which gives you control but adds configuration complexity.</p>
Documentation and Community</h2>
Hugo's documentation is extensive but can be overwhelming. There's a lot to learn, and finding the right approach for your use case sometimes means reading through multiple sections.</p>
Zola's documentation is more concise and organized. It's easier to find what you need quickly, though advanced use cases might require checking GitHub discussions.</p>
Community size favors Hugo significantly. More Stack Overflow answers, more blog posts, more people who've solved the problem you're facing.</p>
When to Choose Hugo</h2>
Pick Hugo if you:</p>

Need proven scalability for massive sites (10,000+ pages)</li>
Want a rich ecosystem of themes and tools</li>
Require complex content modeling and relationships</li>
Need extensive third-party integrations</li>
Value the safety of following the most popular option</li>
</ul>
When to Choose Zola</h2>
Pick Zola if you:</p>

Want the simplest possible setup and maintenance</li>
Prefer building your own designs over adapting themes</li>
Like clean, intuitive templating syntax</li>
Need built-in Sass and don't want to configure build pipelines</li>
Value a focused tool over an extensive ecosystem</li>
Want straightforward multilingual support</li>
</ul>
The Real Difference</h2>
Hugo is a Swiss Army knife—it can do almost anything, but you need to learn which blade to use. Zola is a scalpel—it does fewer things, but it does them precisely and with minimal fuss.</p>
Neither choice is wrong. The question is whether your project needs Hugo's power and ecosystem, or whether Zola's simplicity and elegance will let you ship faster and maintain easier.</p>
For most blogs and documentation sites, Zola is enough. For complex, large-scale projects or when you want maximum flexibility, Hugo delivers. Choose based on your project's needs, not the tool's capabilities.</p>


Zola vs Pelican: Rust Simplicity Meets Python Flexibility
2025-11-13T00:00:00+00:00
Pelican has been around since 2010, making it one of the oldest static site generators still actively maintained. It brought Python's philosophy to static sites and has powered thousands of blogs. Zola is the new contender, built in Rust with a focus on speed and simplicity. Both are excellent tools, but they represent different eras and philosophies of web development.</p>
Installation: Virtual Environments vs Single Binary</h2>
Pelican is a Python package. The typical installation looks like this:</p>
python -m</span> venv pelican-env
</span>source</span> pelican-env/bin/activate
</span>pip</span> install pelican</span>[</span>markdown</span>]
</span>pelican-quickstart
</span></code></pre>
You need Python installed, you'll create a virtual environment (or you should), and you'll manage dependencies through pip. This is standard for Python projects, but it's still setup overhead.</p>
Zola is a single binary:</p>
# Download binary
</span># Add to PATH
</span>zola</span> init my-site
</span></code></pre>
No Python, no virtual environment, no pip. One executable that contains everything. Update Zola by downloading a new binary. Your project has no external dependencies.</p>
This difference matters more than it might seem. With Pelican, you're managing Python versions, virtual environments, and dependency conflicts. With Zola, you download one file and you're done.</p>
Templating: Both Use Jinja-Style Syntax</h2>
Here's where things get interesting: both Pelican and Zola use Jinja-inspired templating.</p>
Pelican uses actual Jinja2, Python's most popular templating engine. If you've worked with Flask or Django, you already know how to template in Pelican. The ecosystem of Jinja2 filters and extensions is available.</p>
Zola uses Tera, which is based on Jinja2 but implemented in Rust. The syntax is nearly identical. If you know Jinja2, you'll understand Tera immediately. The differences are minor—a few filters work differently, and some advanced Jinja2 features aren't available.</p>
In practice, this means the transition from Pelican to Zola (or vice versa) involves minimal template rewriting. Your mental model transfers directly.</p>
Build Speed: Not Even Close</h2>
This is where Rust shows its strength.</p>
Pelican's build speed is acceptable for small to medium sites. For larger sites—think hundreds or thousands of posts—build times can stretch into minutes. Python's interpreted nature and Pelican's plugin architecture add overhead.</p>
Zola rebuilds sites in milliseconds. Even with thousands of pages, builds are measured in seconds, not minutes. During development, changes appear almost instantly. This difference becomes more pronounced as your site grows.</p>
If you're migrating from Pelican and suddenly your builds complete in a fraction of the time, that's not a mistake—that's Rust.</p>
Plugin Ecosystem: Extensibility vs Built-In Features</h2>
Pelican has a mature plugin ecosystem. Need RSS feeds? There's a plugin. Want to integrate with external services? There's probably a plugin. Need custom content processing? Write a Python plugin.</p>
This extensibility is Pelican's strength. If you're comfortable with Python, you can extend Pelican to do almost anything. The plugin API is well-documented, and there are dozens of existing plugins to learn from.</p>
Zola takes the opposite approach: no plugins. Everything you need is built-in. Sass compilation? Included. Syntax highlighting? Built-in. Image processing? It's there. Taxonomies and pagination? Already implemented.</p>
The trade-off is clear: Pelican gives you extensibility through Python. Zola gives you completeness through built-in features. If what you need is already in Zola, you're set. If you need custom behavior, Pelican's plugin system is more flexible.</p>
Content Organization and Metadata</h2>
Both use Markdown with front matter, but they organize content differently.</p>
Pelican's content model is flexible but loose. You can organize files however you want, and Pelican will process them. Metadata is defined in the front matter, and you can add arbitrary custom fields. Categories and tags work as you'd expect from a blog platform.</p>
Zola has a more structured content model with explicit sections and pages. The directory structure maps directly to URL structure. This is more opinionated but also more predictable. Taxonomies (categories, tags, etc.) are first-class concepts with dedicated configuration.</p>
Pelican's flexibility is useful for complex or unusual site structures. Zola's structure is clearer for straightforward blogs and documentation.</p>
Python Integration: Pelican's Unique Advantage</h2>
Here's something Zola can't match: Pelican is Python, which means you can integrate Python code directly.</p>
Want to process data with pandas and generate posts from it? Easy in Pelican. Need to pull data from a Python API client? Write a plugin. Want to use Python's scientific or data visualization libraries? They're available.</p>
This integration is powerful if you're already in the Python ecosystem. If your workflow involves Python data processing, Jupyter notebooks, or scientific computing, Pelican lets you leverage those tools directly.</p>
Zola offers no equivalent. It's a standalone binary with no scripting layer. What you get is what's built-in.</p>
Theme Ecosystem</h2>
Pelican has a substantial collection of themes accumulated over more than a decade. Some are dated, but there are mature, well-maintained options. The community has had years to refine designs.</p>
Zola's theme ecosystem is smaller and newer. There are good themes available, but fewer options overall. You're more likely to build your own or heavily customize what exists.</p>
If you want to grab a theme and start writing immediately, Pelican offers more choices. If you prefer building your own design, both work fine.</p>
Documentation and Community</h2>
Pelican's documentation is comprehensive but shows its age. It's complete, but finding specific information sometimes requires reading through multiple sections. The community is established—most questions have been answered somewhere.</p>
Zola's documentation is modern, well-organized, and easier to navigate. It's written for today's web development practices. The community is smaller but active and helpful.</p>
Stack Overflow and blog posts favor Pelican due to its age, but Zola's GitHub discussions are responsive.</p>
Multilingual Sites</h2>
Pelican supports multiple languages through configuration and the i18n subsites plugin. It works but requires setup and understanding of how Pelican handles translations.</p>
Zola has built-in multilingual support that requires minimal configuration. You create content in different languages, and Zola handles routing automatically. It's simpler and more intuitive.</p>
Configuration</h2>
Pelican uses a Python configuration file (pelicanconf.py</code>). It's flexible—you can run Python code in your config—but it's also verbose. Configuration can become complex.</p>
Zola uses TOML. It's simpler and more declarative. What you see is what you get. There's no code execution in config files, which makes them easier to understand but less flexible.</p>
Deployment and CI/CD</h2>
Both deploy easily to static hosting, but there's a practical difference.</p>
Pelican requires a Python environment in your CI/CD pipeline. You install Python, set up a virtual environment, install dependencies, then build. This works fine but adds steps.</p>
Zola is a single binary. Download it in CI, run it, done. Many CI systems have Zola pre-installed or available through simple package managers. The deployment script is shorter.</p>
When to Choose Pelican</h2>
Pick Pelican if you:</p>

Are already comfortable with Python and its ecosystem</li>
Need to integrate Python libraries or data processing</li>
Want extensive plugin extensibility</li>
Prefer proven, mature technology</li>
Need specific plugins that already exist</li>
Work in a Python-heavy environment</li>
Don't mind managing Python dependencies</li>
</ul>
When to Choose Zola</h2>
Pick Zola if you:</p>

Want zero-dependency installation and deployment</li>
Value fast build times, especially for larger sites</li>
Prefer built-in features over plugins</li>
Want straightforward multilingual support</li>
Like modern, clean documentation</li>
Need simple configuration</li>
Want to avoid dependency management</li>
Don't require Python-specific integrations</li>
</ul>
Migration Path</h2>
If you're considering moving from Pelican to Zola, the good news is that templates will mostly transfer. Both use Jinja-style syntax, so your template knowledge carries over. Content is Markdown in both, though you'll need to adjust front matter format.</p>
The main work is replicating any custom Pelican plugins you rely on. If you use standard features, migration is straightforward. If you have complex Python integrations, staying with Pelican might make more sense.</p>
The Real Question</h2>
Choosing between Pelican and Zola isn't about which is objectively better—it's about which fits your context.</p>
Are you embedded in the Python ecosystem? Do you need Python integrations? Do you value extensibility through code? Pelican makes sense.</p>
Do you want simplicity? Do build times matter? Do you prefer minimal dependencies and modern tooling? Zola is compelling.</p>
Both will give you a fast static site. Pelican does it with Python's flexibility and maturity. Zola does it with Rust's speed and simplicity.</p>
Pick based on your workflow and priorities, not just the tool's features. Sometimes the right choice is the one that gets out of your way and lets you focus on writing.</p>