Updated 2026-11-16
MkDocs JSON-LD: structured data in a theme override
Neither MkDocs nor Material for MkDocs writes structured data, and the social plugin only adds Open Graph tags. Google recommends JSON-LD for structured data (Google Search Central: structured data). On a docs site that means a TechArticle for each page, a BreadcrumbList that matches the navigation and a WebSite on the home page. MkDocs already knows all of that when it renders a page, so a single theme override is enough. Tested on MkDocs 1.6.1; the same block works in Material for MkDocs 9.
1. Turn on a theme override
JSON-LD needs site_url for absolute URLs (the MkDocs SEO guide covers it), and a folder for template overrides (extending the theme):
# mkdocs.yml
site_name: Example Docs
site_url: https://docs.example.com/
site_description: Reference and guides for the Example CLI.
theme:
name: material # or mkdocs
custom_dir: overrides
If you already have overrides/main.html for Open Graph tags, put the code below in the same extrahead block.
2. Build the data in overrides/main.html
{% extends "base.html" %}
{% block extrahead %}
{{ super() }}
{% if page and page.canonical_url %}
{% set desc = page.meta.description if page.meta and page.meta.description else config.site_description %}
{% if page.is_homepage %}
{% set ld = {"@context": "https://schema.org", "@type": "WebSite",
"name": config.site_name, "url": config.site_url, "description": desc} %}
{% else %}
{% set 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_page") | selectattr("is_index") | first %}
{% if index and index != page %}
{% set _ = crumbs.append({"@type": "ListItem", "position": crumbs | length + 1,
"name": section.title, "item": index.canonical_url}) %}
{% endif %}
{% endfor %}
{% set _ = crumbs.append({"@type": "ListItem", "position": 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": crumbs}]} %}
{% endif %}
<script type="application/ld+json">{{ ld | tojson }}</script>
{% endif %}
{% endblock %}
Notes on what it does:
tojsondoes the escaping. Jinja'stojsonfilter writes valid JSON and escapes<,>,&and'as Unicode escapes, so a description containing</script>can't end the tag early. Never build the JSON by hand around{{ page.title }}.- Descriptions come from the page's front matter
description, elsesite_description: the same fallback Material uses for the meta description. - Breadcrumbs follow the nav in
mkdocs.yml, not the URL. A nav section only becomes a crumb when it has an index page (guide/index.md, or Material'snavigation.indexesfeature), because every item except the last needs a real URL. Sections without one are left out. The last item, the page itself, has noitem, which Google accepts. page and page.canonical_urlskips the 404 page and builds withoutsite_url, so no page gets markup with relative URLs.{{ super() }}keeps anything the theme or other overrides already put inextrahead.
On a page at guide/install.md under a Guide section with an index page, the output is (shortened):
<script type="application/ld+json">{"@context": "https://schema.org", "@graph": [{"@type": "TechArticle", "description": "How to install the CLI & its plugins.", "headline": "Install", …}, {"@type": "BreadcrumbList", "itemListElement": [{… "name": "Example Docs", "position": 1}, {"item": "https://docs.example.com/guide/", "name": "Guide", "position": 2}, {"name": "Install", "position": 3, …}]}]}</script>
3. Dates, if you have them
MkDocs doesn't know when a page last changed. With the git-revision-date-localized plugin installed, add "dateModified": page.meta.git_revision_date_localized_raw_iso_datetime to the TechArticle when that value is set. Leave dates out rather than using the build date: a date that changes on every deploy says nothing.
4. Check the build
List built pages with no JSON-LD at all (only 404.html should be left):
mkdocs build && grep -rL --include='*.html' 'application/ld+json' site
Then check a few pages from different sections. The free structured data checker takes a URL or pasted markup and checks each block against the properties Google requires and recommends. Google's Rich Results Test shows how Google reads the breadcrumbs. The free site checker samples pages across a live site and shows which have no structured data, no description or no share image.
Common mistakes
- Breadcrumb items pointing at sections with no page. A crumb URL that 404s makes the trail invalid.
- The same
TechArticlefrom two places, for example a plugin and this override. Search youroverridesfolder and built HTML forld+jsonbefore adding it. - Overriding
extraheadin more than one template without{{ super() }}: the later one silently drops the earlier tags. - Markup for content that isn't on the page. Authors, ratings and versions must also be visible.
Automating it with Headlark
The override gives every page the same generic types. Headlark's build step runs after mkdocs build and writes what each page is missing from its content: one to three JSON-LD blocks with only properties whose values appear on the page (a how-to, an FAQ, a software application), plus missing descriptions, Open Graph tags and alt text. A type you already emit is kept as it is and never added twice, so it works alongside the code above.
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.