Updated 2026-11-20
Zensical SEO: meta descriptions, social cards, JSON-LD and what changes from MkDocs
Zensical is the static site generator from the team behind Material for MkDocs, which has been in maintenance mode since November 2025 with critical fixes through May 2027. It builds existing mkdocs.yml projects as well as its own zensical.toml, so many docs teams are moving now. Out of the box its pages carry a title, a canonical link and a meta description only if you set one: no Open Graph tags, no preview image and no structured data. Two built-in plugins and one theme override cover all of that. One catch for anyone moving from MkDocs: Zensical renders templates with a different engine, and common Jinja tricks in old overrides stop the build.
Tested on Zensical 0.1.2: every snippet below was built, both from zensical.toml and from an existing mkdocs.yml, and the output checked.
1. site_url first
The canonical link, og:url, the preview image URLs and sitemap.xml are all built from site_url. Without it, Zensical leaves the canonical out and warns that social cards are generated but not linked.
# zensical.toml
[project]
site_url = "https://docs.example.com/"
site_name = "Example Docs"
site_description = "Reference and guides for the Example CLI."
In an existing mkdocs.yml the same keys (site_url, site_name, site_description) keep working. Check the built HTML: grep -o 'rel="canonical" href="[^"]*"' site/index.html should print your production address.
2. Meta descriptions: front matter, then the meta-descriptions plugin
The theme writes <meta name="description"> from the page's description front matter and otherwise falls back to site_description, so every page without its own description shares the site one. Write descriptions for the pages that matter most:
---
description: How to install the CLI and its plugins on macOS, Linux and Windows.
---
# Install
For the rest, Zensical has the meta-descriptions plugin built in (it also accepts the MkDocs plugin's name in mkdocs.yml). It fills in pages that have no description of their own from their first paragraph, and leaves front matter descriptions alone:
[project.plugins.meta-descriptions]
trim = true
max_length = 155
- It skips admonitions. On a page that opens with a
!!! note, it took the first real paragraph after it. - Without
trim, long paragraphs go in whole. A 360-character first paragraph became a 360-character description. Withtrim = trueit's cut at a word boundary, mid-sentence and without an ellipsis, so the result still reads as a fragment. - It only looks above the first subheading. A page that opens with a code block, or whose first paragraph sits under an
##heading, gets nothing and falls back tosite_description. Reference pages often look like that.
The build log tells you how many pages it covered, for example meta-descriptions: Added meta descriptions to 5 of 5 pages, 3 using the first paragraph.
3. Open Graph tags and preview images: the social plugin
Zensical has Material's social cards built in. Turning the plugin on adds the Open Graph and X tags as well as the images:
[project.plugins.social]
Or - social under plugins in mkdocs.yml. Each page then gets a 1200×630 PNG card under assets/images/social/ with the site name, page title and description, plus og:type, og:title, og:description, og:image with its type and size, og:url, and twitter:card set to summary_large_image. Things to know:
- The description on the card and in
og:descriptionis the page's meta description, so it's only as good as step 2. Pages with no description get a card without one. og:titleis the browser title, for exampleInstall - Example Docs; on the home page it's just the site name.- The X tags are written as
property="twitter:…", notname=. X also reads the Open Graph tags, so previews still work.
Check a card before you ship: open site/assets/images/social/ after a build. If a card still doesn't show up when the link is shared, og:image not showing covers the other causes.
4. JSON-LD: one override that builds on both Zensical and MkDocs
Neither Zensical nor its social plugin writes structured data. The pattern from MkDocs JSON-LD works here too: a theme override that adds a TechArticle and a BreadcrumbList on every page and a WebSite on the home page. Point the theme at an overrides folder:
[project.theme]
custom_dir = "overrides"
Then put this in overrides/main.html:
{% extends "base.html" %}
{% block extrahead %}
{{ super() }}
{% if page and page.meta and page.meta.robots %}
<meta name="robots" content="{{ page.meta.robots }}">
{% endif %}
{% if page and page.canonical_url %}
{% set desc = page.meta.description if page.meta and page.meta.description else config.site_description %}
{% if page.url in ["", "index.html"] %}
{% set ld = {"@context": "https://schema.org", "@type": "WebSite",
"name": config.site_name, "url": config.site_url, "description": desc} %}
{% else %}
{% set ns = namespace(crumbs=[{"@type": "ListItem", "position": 1, "name": config.site_name, "item": config.site_url}]) %}
{% for section in page.ancestors | reverse %}
{% set index = section.children | selectattr("is_index") | first %}
{% if index and index.url != page.url %}
{% set ns.crumbs = ns.crumbs + [{"@type": "ListItem", "position": ns.crumbs | length + 1,
"name": section.title, "item": index.canonical_url}] %}
{% endif %}
{% endfor %}
{% set ns.crumbs = ns.crumbs + [{"@type": "ListItem", "position": ns.crumbs | length + 1, "name": page.title}] %}
{% set ld = {"@context": "https://schema.org", "@graph": [
{"@type": "TechArticle", "headline": page.title, "description": desc,
"url": page.canonical_url, "inLanguage": config.theme.language or "en",
"isPartOf": {"@type": "WebSite", "name": config.site_name, "url": config.site_url}},
{"@type": "BreadcrumbList", "itemListElement": ns.crumbs}]} %}
{% endif %}
<script type="application/ld+json">{{ ld | tojson }}</script>
{% endif %}
{% endblock %}
It builds unchanged in MkDocs and Material for MkDocs, so you can add it before the move. Zensical renders templates with a Rust implementation of Jinja, and three things that work in MkDocs don't work there:
- No list methods.
crumbs.append(...)stops the build withsequence has no method named append. Build lists with+on anamespace(), as above; a plainsetinside aforloop doesn't survive the loop in either engine. page.is_homepageis empty, so the home page would get aTechArticle. Testpage.urlinstead.is_pageis empty on nav items, soselectattr("is_page")drops every page and the breadcrumbs lose their sections.is_indexworks on its own.
tojson escapes <, > and & as \u003c, \u003e and \u0026 in both engines, so a description containing </script> can't end the tag early. The description in the JSON-LD comes from the same place as the meta tag, including descriptions the meta-descriptions plugin wrote. The 404 page has no canonical URL, so it gets no JSON-LD.
5. noindex and the sitemap
Zensical has no robots setting per page. The second block in the override above writes one from front matter:
---
robots: noindex
---
The page still appears in sitemap.xml, and we found no per-page switch to leave it out, so a page you want gone for good is better deleted or redirected. The sitemap lists every page with its loc only, without lastmod; Google ignores changefreq and priority anyway. Zensical doesn't write a robots.txt: put one in docs/ with User-agent: * and Sitemap: https://docs.example.com/sitemap.xml.
6. Check the build
zensical build
grep -rL --include='*.html' 'name="description"' site
grep -rhoE --include='*.html' '<meta name="description" content="[^"]*"' site | sort | uniq -c | sort -rn | head
grep -rL --include='*.html' 'application/ld+json' site
The first lists pages without a description, the second shows descriptions shared by several pages (usually the site_description fallback), the third pages without JSON-LD (the 404 page is expected). 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
The meta-descriptions plugin copies the first paragraph, cut to length or not at all, and the site description covers every page that starts with code or a subheading. Headlark's build step runs after zensical build on the HTML in site/ and writes those tags from each page's whole content. It's a Node.js CLI, so the build environment needs Node 20 or newer next to Python; GitHub Actions, Netlify and Cloudflare Pages all have it. Add it once with npm i -D headlark, then:
zensical build
npx headlark site --site-url https://docs.example.com/
Use the same address as site_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, such as a social card, 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.