Updated 2026-11-18

Zola SEO: meta descriptions, Open Graph, JSON-LD and the sitemap

Zola writes plain static HTML and builds a sitemap.xml and robots.txt for you, but everything in <head> comes from your templates: Zola adds no meta description, canonical, Open Graph tags or structured data on its own. This guide gives you one head template that covers all of them, for Zola 0.23 and newer. 0.23 moved to Tera 2, so templates written for older releases (and many themes) no longer build; the snippets here use the new syntax (Zola changelog, Tera 2 migration).

Tested on Zola 0.23.6: every snippet below was built and the output checked.

1. base_url first

Every absolute URL Zola writes (current_url, page.permalink, get_url, the sitemap and feeds) is built from base_url. Set it to the production address, and give the site a description and a default preview image:

# config.toml
base_url = "https://docs.example.com"
title = "Example Docs"
description = "Reference and guides for the Example CLI."

[extra]
og_image = "og/default.png"   # a file in static/

Check the built HTML: grep -o 'property="og:url" content="[^"]*"' public/index.html should print your production address.

2. One head template for every page

Put this in templates/base.html and have index.html, section.html and page.html extend it. Page templates get page, section and index templates get section; the first line picks whichever exists.

{%- set p = page or section %}
{%- set desc = p.description or ((p?.summary or "") | striptags | trim) or config.description %}
{%- set img = get_url(path=p.extra?.image or config.extra.og_image) %}
<title>{% if p.path != "/" %}{{ p.title }} · {% endif %}{{ config.title }}</title>
<meta name="description" content="{{ desc }}">
<link rel="canonical" href="{{ current_url }}">
{%- if p.extra?.noindex %}<meta name="robots" content="noindex">{% endif %}
<meta property="og:type" content="{% if page %}article{% else %}website{% endif %}">
<meta property="og:title" content="{{ p.title or config.title }}">
<meta property="og:description" content="{{ desc }}">
<meta property="og:url" content="{{ current_url }}">
<meta property="og:image" content="{{ img }}">
<meta name="twitter:card" content="summary_large_image">
{%- if page %}
{%- set ld = {"@context": "https://schema.org", "@type": "TechArticle", "headline": page.title, "description": desc, "url": page.permalink, "image": img} %}
{%- if page.date %}{% set ld = {...ld, "datePublished": page.date, "dateModified": page.updated or page.date} %}{% endif %}
<script type="application/ld+json">{{ ld | json_encode | replace(from="<", to="\\u003c") | safe }}</script>
<script type="application/ld+json">{"@context":"https://schema.org","@type":"BreadcrumbList","itemListElement":[
{%- for a in page.ancestors %}{% set s = get_section(path=a) %}{"@type":"ListItem","position":{{ loop.index }},"name":{{ s.title | json_encode | replace(from="<", to="\\u003c") | safe }},"item":{{ s.permalink | json_encode | safe }}},{% endfor -%}
{"@type":"ListItem","position":{{ page.ancestors | length + 1 }},"name":{{ page.title | json_encode | replace(from="<", to="\\u003c") | safe }}}]}</script>
{%- endif %}

What it does:

The home page is a section, so set its title in content/_index.md; that is what og:title shows when someone shares your root URL.

3. Preview images per page

Set a path in static/ or, since 0.23, a colocated file with an @/ path. For a page bundle (content/docs/install/index.md with cover.png next to it):

+++
title = "Install the CLI"
description = "Install the CLI on macOS, Linux and Windows, with checksums."
date = 2026-10-01
updated = 2026-11-10

[extra]
image = "@/docs/install/cover.png"
+++

get_url resolves it to https://docs.example.com/docs/install/cover.png. If a card still has no picture, og:image not showing covers the other causes.

4. Keeping pages out of search

Zola has no built-in robots tag; the template above writes noindex when a page sets noindex = true under [extra]. The built-in sitemap still lists that page, so override it with templates/sitemap.xml to leave those out:

<?xml version="1.0" encoding="UTF-8"?>
<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
    {%- for sitemap_entry in entries %}{% if not sitemap_entry.extra?.noindex %}
    <url>
        <loc>{{ sitemap_entry.permalink | escape_xml | safe }}</loc>
        {%- if sitemap_entry.updated %}
        <lastmod>{{ sitemap_entry.updated }}</lastmod>
        {%- endif %}
    </url>
    {%- endif %}{% endfor %}
</urlset>

That is Zola's own sitemap template with one condition added. Pages with render = false aren't built and aren't in the sitemap at all.

5. The sitemap and robots.txt

6. Check the build

zola build
grep -rL --include='*.html' 'name="description"' public
grep -rhoE --include='*.html' '<meta name="description" content="[^"]*"' public | sort | uniq -c | sort -rn | head
grep -rL --include='*.html' 'application/ld+json' public

The first lists pages without a description, the second shows descriptions shared by several pages (sections without a description of their own fall back to the site one), the third pages without JSON-LD. Duplicate titles and descriptions on a docs site goes through fixing those. To see the result as Google and the link previewers do, run a few deployed pages through the free SEO checker or the structured data checker, or up to 50 pages from your sitemap through the site checker.

Automating it with Headlark

A head template fills every page from the same fallbacks: the site description on each section, and on pages without a front matter description, whatever came before <!-- more -->. Headlark's build step runs after zola build on the HTML in public/ and writes those tags from each page's content. It's a Node.js CLI, so the build environment needs Node 20 or newer next to Zola; GitHub Actions, Netlify and Cloudflare Pages all have it. Add it once with npm i -D headlark, then:

zola build
npx headlark public --site-url https://docs.example.com/

Use the same address as base_url. Set HEADLARK_KEY in the build environment.

Try it

Try it free for 14 days on one site and up to 500 pages, no card needed. Add your site, copy its secret key, and your next build ships with SEO.