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/
zola servereplaces it with the local address, so check tags in the output ofzola build, not in the dev server.--base-urlwins over the config. If CI passes one (Netlify deploy previews often do), make sure production builds get the production address.
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:
- Description: the front matter
description, then the page summary (the text before<!-- more -->, only set when the page has that divider), then the site description. Tera escapes the values, so quotes and ampersands don't break the tags. - Canonical and
og:url:current_url, so only as good asbase_url. - Image:
extra.imagefrom front matter, else the site default. Use a PNG or JPG around 1200×630; previewers don't render SVG. - JSON-LD on regular pages: a
TechArticlewith dates when the page has adate(no null fields when it doesn't), and aBreadcrumbListfrompage.ancestors, home first.json_encodedoesn't escape<, so thereplaceturns it into\u003c; a title containing</script>can't end the script tag early. - Tera 2 details:
orreturns the first value that is set,?.stops at a missing field instead of failing the build, and{...ld, ...}extends a map. On Zola 0.22 and older, none of these parse.
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
sitemap.xmllists every page and section.lastmodcomes fromupdated, elsedate; pages with neither get none. Google useslastmodwhen it's accurate, so setupdatedwhen you change a page.robots.txtallows everything and already points at the sitemap. Override it withtemplates/robots.txtif you need rules.
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.
- Each page gets a title, a description, Open Graph and X tags written from its own content, and alt text for images that have none.
- An existing
og:image, fromextra.imageor the site default, is kept. Headlark doesn't create images. - Your canonical, robots tags and JSON-LD types are kept.
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.