Updated 2026-11-18

Jekyll JSON-LD: breadcrumbs and TechArticle next to jekyll-seo-tag

If your Jekyll site uses jekyll-seo-tag (GitHub Pages includes it), every page already has one JSON-LD block: WebSite on the home page, BlogPosting for posts and WebPage for everything else. Two things are missing on most sites: a BreadcrumbList, which Google can show instead of the raw URL in results, and a more specific type for documentation pages than WebPage. Google recommends JSON-LD for structured data (Google Search Central: structured data). Both fit in one include and a few lines of config, without replacing the plugin. The Jekyll SEO guide covers the plugin itself. Tested on Jekyll 3.10 (the version GitHub Pages runs) with jekyll-seo-tag 2.9.

1. Set url

Structured data needs absolute URLs, so _config.yml needs url (and baseurl if the site lives in a subfolder):

# _config.yml
title: Example Docs
url: https://docs.example.com
baseurl: ""
plugins:
  - jekyll-seo-tag

2. Docs pages as TechArticle, from front matter defaults

jekyll-seo-tag reads the type from seo.type in front matter (advanced usage). Set it for a whole folder with front matter defaults instead of on every page:

# _config.yml
defaults:
  - scope:
      path: "docs"
    values:
      seo:
        type: TechArticle

The plugin's block keeps its headline, description, url and dates; only @type changes. Pages that set their own seo.type keep it.

3. Breadcrumbs in _includes/breadcrumbs-ld.html

{%- if page.url != "/" and page.url != "/404.html" and site.url -%}
{%- assign parts = page.url | split: "/" -%}
{%- assign path = "/" -%}
{%- assign pos = 1 -%}
{%- capture items -%}
{"@type":"ListItem","position":1,"name":{{ site.title | jsonify }},"item":{{ "/" | absolute_url | jsonify }}}
{%- for part in parts -%}
  {%- if part == "" or forloop.last -%}{%- continue -%}{%- endif -%}
  {%- assign path = path | append: part | append: "/" -%}
  {%- assign section = site.pages | where: "url", path | first -%}
  {%- if section.title -%}
    {%- assign pos = pos | plus: 1 -%}
,{"@type":"ListItem","position":{{ pos }},"name":{{ section.title | jsonify }},"item":{{ section.url | absolute_url | jsonify }}}
  {%- endif -%}
{%- endfor -%}
,{"@type":"ListItem","position":{{ pos | plus: 1 }},"name":{{ page.title | default: site.title | jsonify }}}
{%- endcapture -%}
<script type="application/ld+json">{"@context":"https://schema.org","@type":"BreadcrumbList","itemListElement":[{{ items | replace: "<", "\u003c" }}]}</script>
{%- endif -%}

Include it in the <head> of your layout, after the plugin's tag:

<!-- _layouts/default.html -->
{% seo %}
{% include breadcrumbs-ld.html %}

Notes on what it does:

On /docs/install/ with a docs/index.md titled Docs, the output is:

<script type="application/ld+json">{"@context":"https://schema.org","@type":"BreadcrumbList","itemListElement":[{"@type":"ListItem","position":1,"name":"Example Docs","item":"https://docs.example.com/"},{"@type":"ListItem","position":2,"name":"Docs","item":"https://docs.example.com/docs/"},{"@type":"ListItem","position":3,"name":"Install"}]}</script>

4. Check the build

List built pages with no breadcrumbs (only the home page and 404.html should be left), then pages with no JSON-LD at all:

bundle exec jekyll build
grep -rL --include='*.html' 'BreadcrumbList' _site
grep -rL --include='*.html' 'application/ld+json' _site

Then check a few pages from different folders. 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 include and defaults give every page generic types. Headlark's build step runs after jekyll 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. jekyll-seo-tag's block and a type you already emit are kept as they are 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.