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:
- Escaping. Jekyll's
jsonifywrites valid JSON strings but does not escape<, so a title containing</script>would end the tag early. The finalreplaceturns every<into the JSON escape\u003c, which parsers read as the same character. Never paste{{ page.title }}into the JSON withoutjsonify. - Crumbs follow the URL. For
/docs/install/it looks for a page at/docs/insite.pagesand uses its title. A folder without a page (or without a title) is left out, because every crumb except the last needs a real URL. That also drops the date folders in post URLs like/2024/05/01/hello.html, so a post gets Home › Post. The last item, the page itself, has noitem, which Google accepts. - Collections. Section pages are looked up in
site.pagesonly. If your section index pages live in a collection, extend the lookup with| concat: site.docs(your collection's name). - Skipped pages. The home page and
404.htmlget no breadcrumbs, and neither does a build withouturl, so no page ships relative URLs. - A separate block. The breadcrumbs go in their own
<script>next to the plugin's. Google reads several JSON-LD blocks on one page, and this way plugin updates can't break your code.
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
- A second hand-written
WebPageorArticleblock next to the plugin's. Change the plugin's type withseo.typeinstead of adding another. - Breadcrumb items pointing at folders with no page. A crumb URL that 404s makes the trail invalid; the include leaves those out.
- No
descriptionin front matter. jekyll-seo-tag falls back to the site description or an excerpt, so the JSON-LD says the same thing on many pages. - Markup for content that isn't on the page. Authors, ratings and versions must also be visible.
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.