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

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:

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:

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.

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.