---

name: creating-zola-static-sites description: Build static sites with the Zola generator (Rust-based SSG). Handles project initialization, config.toml configuration, Tera templates, Markdown content (sections via _index.md, pages via *.md), taxonomies, image processing, and deployment. Use for Zola project setup, Tera templating, _index.md structure, RSS/Atom feeds, syntax highlighting, or deployment to Netlify/Cloudflare/GitHub Pages/Vercel/Firebase. Also covers Zola+Astro hybrid architectures.

Creating Zola Static Sites

Single-binary static site generator. Built-in Sass, image processing, Tera templating.

Quick Start

CopyNew Project:
- [ ] zola init my-site && cd my-site
- [ ] Edit config.toml: set base_url
- [ ] IF using theme: skip next step (theme provides templates)
- [ ] IF no theme: copy templates from skill assets/
- [ ] zola serve → http://127.0.0.1:1111 loads
- [ ] zola check → exit code 0

Commands

Core: Sections vs Pages

_ prefix = section (listing); no prefix = page (content):

Copycontent/
├── _index.md        # section: /
├── about.md         # page: /about/
└── blog/
    ├── _index.md    # section: /blog/
    └── post.md      # page: /blog/post/

Frontmatter

section (_index.md):

Copy+++
title = "Blog"
sort_by = "date"        # date|title|weight|none
paginate_by = 10
+++

page (*.md):

Copy+++
title = "My Post"
date = 2024-01-15       # NO QUOTES or sorting breaks
[taxonomies]
tags = ["rust"]
+++

Internal Links

Build-validated with @/ prefix:

Copy[About](@/about.md)
[Blog](@/blog/_index.md)

Workflows

Create Blog

CopyBlog Setup:
- [ ] Create content/blog/_index.md with sort_by="date"
- [ ] Create post: content/blog/2024-01-15-hello.md
- [ ] IF multilingual: add blog/_index.fr.md per language
- [ ] zola serve → /blog/ shows listing (empty if no posts yet)
- [ ] zola serve → /blog/hello/ shows post
- [ ] IF pagination: add more posts than paginate_by to test
- [ ] zola check → passes

Add Taxonomies

CopyTaxonomy Setup:
- [ ] config.toml: taxonomies = [{name = "tags", feed = true}]
- [ ] Page frontmatter: [taxonomies] tags = ["value"]
- [ ] IF need categories: add {name = "categories"} to array
- [ ] IF term has spaces: use slugified URL (/tags/my-tag/)
- [ ] zola serve → /tags/ lists tags
- [ ] zola serve → /tags/rust/ shows posts

Deploy

CopyProduction Deploy:
- [ ] zola check → passes (use --skip-external-links if slow)
- [ ] zola build → no errors
- [ ] ls public/index.html → exists
- [ ] IF feeds enabled: ls public/atom.xml → exists

Reference Files

Assets

Copy from skill assets/ directory:

Common Mistakes

Troubleshooting

Debug: {{ __tera_context }} in template shows all variables.

Verbose: RUST_LOG=zola=info zola build

When Not to Use

• Other SSGs: Hugo, Jekyll, Eleventy use different syntax
• General Markdown: Questions without Zola context
• Pure Astro: Projects without Zola integration