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:

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

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.