$ cat static-site-generation-with-zola.md

8 min read
zolastatic-sitesrustweb-developmentjamstack

I’ve tried a lot of static site generators over the years, and let me tell you—Zola is something special. When I first discovered it, I was skeptical (another static site generator, really?), but after building this blog with it, I’m genuinely excited about what it brings to the table. Let me share why Zola has become my go-to tool for static sites.

Why Zola Won Me Over

After wrestling with Jekyll’s Ruby dependencies, fighting with Gatsby’s complexity, and getting lost in Hugo’s documentation, Zola felt like a breath of fresh air:

Performance That Actually Matters

  • Single Binary: Download one file, and you’re done. No Ruby gems, no Node modules, no Python virtual environments—just one binary that works
  • Rust-Powered Speed: Builds that finish before you can alt-tab to check Twitter. Seriously, it’s that fast
  • Smart Optimization: Automatic minification and optimization without you having to think about it

Developer Experience That Doesn’t Suck

  • Everything Built-in: Syntax highlighting, search, RSS feeds—it’s all there out of the box
  • Live Reload: Make a change, see it instantly. No waiting, no manual refreshes
  • Documentation That Makes Sense: Clear, comprehensive guides that actually help you get things done

Modern Features Without the Complexity

  • Sass Support: CSS preprocessing that just works
  • Shortcodes: Reusable content components that make your life easier
  • Smart Taxonomies: Tagging and categorization that’s flexible without being overwhelming
  • Multilingual Support: First-class internationalization when you need it

Getting Started with Zola

Installation (The Easy Part)

Installing Zola is refreshingly simple—no dependency hell, no version conflicts, just grab the binary and go:

# macOS (my personal favorite)
brew install zola

# Windows
scoop install zola
# or if you prefer Chocolatey
choco install zola

# Linux
snap install --edge zola

Can’t use a package manager? No problem—just download the binary from the official releases. One file, that’s it.

Your First Site (In About 30 Seconds)

Here’s where Zola really shines—getting started is almost embarrassingly easy:

# Create a new site
zola init my-blog

# Navigate to the directory
cd my-blog

# Start the development server
zola serve

And just like that, you have a working site! Zola creates this clean structure:

my-blog/
├── config.toml
├── content/
├── sass/
├── static/
├── templates/
└── themes/

Site Configuration

The config.toml file is the heart of your Zola site. Here’s a comprehensive configuration based on this blog:

# Basic site information
base_url = "https://yourdomain.com"
title = "Your Blog Title"
description = "Your blog description"

# Language and locale
default_language = "en"

# Build settings
compile_sass = true
minify_html = true
build_search_index = true
generate_feeds = true

# Markdown configuration
[markdown]
highlight_code = true
highlight_theme = "base16-ocean-dark"
render_emoji = true
external_links_target_blank = true
external_links_no_follow = true
external_links_no_referrer = true
smart_punctuation = true

# Taxonomies for organization
[[taxonomies]]
name = "tags"
feed = true

[[taxonomies]]
name = "categories"
feed = true

# Custom configuration
[extra]
author = "Your Name"
github_username = "yourusername"
show_reading_time = true
show_tags = true

Content Structure and Organization

Page Types

Zola supports different types of content:

  1. Regular Pages: Individual content files
  2. Sections: Collections of pages with their own index
  3. Index Pages: Special _index.md files for section homepages

Creating Content

Create a blog post:

+++
title = "My First Post"
description = "A brief description of the post"
date = 2025-01-18
updated = 2025-01-18

[taxonomies]
tags = ["tutorial", "zola"]
categories = ["web-development"]

[extra]
+++

Your content goes here...

<!-- more -->

Content after this comment appears only on the full post page.

Content Organization

content/
├── _index.md          # Homepage
├── about.md           # About page
├── projects.md        # Projects page
├── blog/
│   ├── _index.md      # Blog section index
│   ├── post-1.md
│   └── post-2.md
└── docs/
    ├── _index.md
    └── guide.md

Theming and Templates

Template Hierarchy

Zola uses the Tera templating engine with a clear hierarchy:

templates/
├── base.html          # Base template
├── index.html         # Homepage template
├── page.html          # Single page template
├── section.html       # Section listing template
├── taxonomy_list.html # Tag/category listing
└── taxonomy_single.html # Single tag/category

Creating a Base Template

<!DOCTYPE html>
<html lang="{{ config.default_language }}">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>
        {%- if page.title -%}
            {{ page.title }} | {{ config.title }}
        {%- elif section.title -%}
            {{ section.title }} | {{ config.title }}
        {%- else -%}
            {{ config.title }}
        {%- endif -%}
    </title>
    
    <meta name="description" content="
        {%- if page.description -%}
            {{ page.description }}
        {%- elif section.description -%}
            {{ section.description }}
        {%- else -%}
            {{ config.description }}
        {%- endif -%}
    ">
    
    <link rel="stylesheet" href="/style.css">

    {% if config.generate_feeds %}
    <link rel="alternate" type="application/atom+xml" title="RSS" href="/atom.xml">
    {% endif %}
</head>
<body>
    <header>
        <nav>
            <a href="/">{{ config.title }}</a>
            {% if config.extra.menu %}
                {% for item in config.extra.menu %}
                <a href="{{ item.url }}">{{ item.name }}</a>
                {% endfor %}
            {% endif %}
        </nav>
    </header>
    
    <main>
        {% block content %}{% endblock content %}
    </main>
    
    <footer>
        <p>&copy; {{ now() | date(format="%Y") }} {{ config.extra.author }}</p>
    </footer>
</body>
</html>

Page Template

{% extends "base.html" %}

{% block content %}
<article>
    <header>
        <h1>{{ page.title }}</h1>
        {% if page.date %}
        <time datetime="{{ page.date }}">
            {{ page.date | date(format="%B %d, %Y") }}
        </time>
        {% endif %}
        
        {% if page.extra.reading_time and config.extra.show_reading_time %}
        <span>{{ page.reading_time }} min read</span>
        {% endif %}
    </header>
    
    <div class="content">
        {{ page.content | safe }}
    </div>
    
    {% if page.taxonomies.tags and config.extra.show_tags %}
    <footer>
        <div class="tags">
            {% for tag in page.taxonomies.tags %}
            <a href="{{ get_taxonomy_url(kind='tags', name=tag) }}">#{{ tag }}</a>
            {% endfor %}
        </div>
    </footer>
    {% endif %}
</article>
{% endblock content %}

Advanced Features

Shortcodes

Shortcodes allow you to create reusable content components. Create them in templates/shortcodes/:

<!-- templates/shortcodes/alert.html -->
<div class="alert alert-{{ type }}">
    {% if title %}
    <h4>{{ title }}</h4>
    {% endif %}
    {{ body | markdown | safe }}
</div>

Use in content:




<div class="alert alert--warning">
    
    <div class="alert__title">
        <span class="alert__icon">
            ⚠️
            
        </span>
        <strong>Important</strong>
    </div>
    
    
    <div class="alert__content">
        <p>This is a warning message.</p>

    </div>
</div>

Search Functionality

Enable search in config.toml:

build_search_index = true

[search]
include_title = true
include_description = true
include_content = true

Create a search page:

<!-- templates/search.html -->
{% extends "base.html" %}

{% block content %}
<div id="search">
    <input type="text" id="search-input" placeholder="Search...">
    <div id="search-results"></div>
</div>

<script src="/search_index.en.js"></script>
<script src="/elasticlunr.min.js"></script>
<script>
    // Search implementation
    const searchIndex = elasticlunr.Index.load(window.searchIndex);
    const searchInput = document.getElementById('search-input');
    const searchResults = document.getElementById('search-results');
    
    searchInput.addEventListener('input', function() {
        const query = this.value;
        if (query.length < 2) {
            searchResults.innerHTML = '';
            return;
        }
        
        const results = searchIndex.search(query, {
            fields: {
                title: {boost: 2},
                body: {boost: 1}
            }
        });
        
        displayResults(results);
    });
</script>
{% endblock content %}

Custom Sass Styling

Zola compiles Sass automatically. Create sass/style.scss:

// Variables
$primary-color: #2d3748;
$secondary-color: #4a5568;
$accent-color: #3182ce;
$background-color: #f7fafc;
$text-color: #2d3748;

// Base styles
* {
    box-sizing: border-box;
}

body {
    font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
    line-height: 1.6;
    color: $text-color;
    background-color: $background-color;
    margin: 0;
    padding: 0;
}

// Terminal-inspired theme
.terminal {
    background-color: #1a202c;
    color: #e2e8f0;
    font-family: 'Fira Code', 'Monaco', 'Consolas', monospace;
    
    .prompt {
        color: #68d391;
        
        &::before {
            content: '$ ';
        }
    }
}

// Responsive design
@media (max-width: 768px) {
    .container {
        padding: 0 1rem;
    }
    
    nav {
        flex-direction: column;
        
        a {
            margin: 0.25rem 0;
        }
    }
}

Deployment Strategies

Cloudflare Pages

  1. Connect your GitHub repository to Cloudflare Pages
  2. Set build command: zola build
  3. Set output directory: public
  4. Deploy automatically on push

Netlify

Create netlify.toml:

[build]
publish = "public"
command = "zola build"

[build.environment]
ZOLA_VERSION = "0.18.0"

[[headers]]
for = "/*"
[headers.values]
X-Frame-Options = "DENY"
X-XSS-Protection = "1; mode=block"
X-Content-Type-Options = "nosniff"
Referrer-Policy = "strict-origin-when-cross-origin"

GitHub Pages

Create .github/workflows/deploy.yml:

name: Deploy to GitHub Pages

on:
  push:
    branches: [ main ]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v3
    
    - name: Setup Zola
      uses: taiki-e/install-action@v2
      with:
        tool: [email protected]
    
    - name: Build site
      run: zola build
    
    - name: Deploy to GitHub Pages
      uses: peaceiris/actions-gh-pages@v3
      with:
        github_token: ${{ secrets.GITHUB_TOKEN }}
        publish_dir: ./public

Performance Optimization

Image Optimization

Use the resize_image function in templates:

{% set resized_image = resize_image(path="images/large-image.jpg", width=800, height=600, op="fit_width") %}
<img src="{{ resized_image.url }}" alt="Description" loading="lazy">

Minification

Enable in config.toml:

minify_html = true

Caching Headers

Configure appropriate cache headers in your deployment platform for static assets.

Best Practices

Content Organization

  • Use clear, descriptive filenames
  • Organize content in logical sections
  • Implement consistent frontmatter structure

SEO Optimization

  • Write descriptive meta descriptions
  • Use semantic HTML structure
  • Implement proper heading hierarchy
  • Add structured data when appropriate

Performance

  • Optimize images before adding to static folder
  • Use lazy loading for images
  • Minimize external dependencies
  • Implement proper caching strategies

Troubleshooting Common Issues

Build Errors

  • Check template syntax with zola check
  • Validate frontmatter TOML syntax
  • Ensure all referenced files exist

Styling Issues

  • Verify Sass compilation with zola build --drafts
  • Check CSS specificity conflicts
  • Test responsive design across devices

Content Problems

  • Validate markdown syntax
  • Check internal link references
  • Ensure proper date formatting

Why I’m Sticking with Zola

After building this blog and several other sites with Zola, I’m convinced it’s found the sweet spot between simplicity and power. It’s fast enough to make you smile, feature-rich enough to handle real projects, and simple enough that you spend time writing content instead of fighting with tooling.

The secret sauce? Start simple and add complexity only when you need it. Focus on your content first—that’s what your readers care about anyway. Then gradually layer on the advanced features like search, shortcodes, and custom styling.

Zola gets out of your way and lets you build. In a world of increasingly complex web development tools, that’s refreshingly rare.

Want to see these concepts in action? This very blog is built with Zola using the approaches I’ve described here. The source code is available if you want to peek under the hood and see how it all comes together.