Schema Markup·4 min read

Breadcrumbs in Search Results: BreadcrumbList Guide

Documentation sites go deep fast. A page like /docs/api/v2/webhooks/retries sits five levels down, and its search snippet is unreadable as a raw URL string. Breadcrumbs in search results replace that string with a legible trail, Docs to API to Webhooks, and BreadcrumbList markup is how you ask for the swap. This guide covers the position rules, a worked example from a fictional docs site, and the mismatches that make Google shrug and print the URL anyway.

Open the tool All insights

How breadcrumbs in search results actually get there

Google can infer a trail from your URL path on its own, and for deep docs URLs it often tries. The inference is mechanical, though: a segment like v2 becomes the crumb V2, and api stays lowercase nonsense. BreadcrumbList markup replaces guesswork with your own labels, so the snippet reads API Reference instead of a slug fragment.

The benefit concentrates at depth. A three level marketing site barely notices; a documentation portal where every meaningful page sits four or more levels down gains readable snippets across its entire long tail, and readable snippets are what people click. There's a second audience too: the trail exposes your information architecture to crawlers as explicit parent and child relationships, which helps them attribute deep pages to the right section of the site.

A worked BreadcrumbList example from a docs site

Take a fictional developer portal, devhandbook.io, and its webhooks page at /docs/api/webhooks. Running Analyze page and tidying the names produces: {"@context":"https://schema.org","@type":"BreadcrumbList","itemListElement":[{"@type":"ListItem","position":1,"name":"Home","item":"https://devhandbook.io/"},{"@type":"ListItem","position":2,"name":"Docs","item":"https://devhandbook.io/docs"},{"@type":"ListItem","position":3,"name":"API Reference","item":"https://devhandbook.io/docs/api"},{"@type":"ListItem","position":4,"name":"Webhooks","item":"https://devhandbook.io/docs/api/webhooks"}]}.

The third crumb is the tell: the path segment is api, but the name reads API Reference because that's what the site's navigation calls it. That renaming step is where derived trails become good trails.

Breadcrumb position rules that actually matter

The breadcrumb position rules are strict and short. Positions are integers starting at 1, strictly sequential, no gaps, no repeats, ordered from the root down to the current page. Each ListItem carries a name, and every item except optionally the last carries an item URL pointing at a live, indexable page.

Google tolerates a final crumb without a URL, since the searcher is already headed to that page; this generator includes it, which is equally valid. What it won't tolerate is a trail running backwards, current page first, a surprisingly common hand-coding inversion that reads as nonsense to the parser.

Matching visible breadcrumbs to the markup

Matching visible breadcrumbs is the trust test. If your docs template renders Home, Docs, API Reference, Webhooks across the top of the page, the BreadcrumbList should carry those four names in that order, and not a five level fantasy hierarchy the reader never sees. Divergence tells Google one of the two is wrong, and it stops trusting both.

This cuts against a common temptation on deep sites: compressing the visible trail for design reasons while keeping the full path in schema. Compress both or neither. The markup describes the page's navigation reality, it doesn't improve on it. If the designed trail hides middle levels behind an ellipsis on mobile, that's fine, since the full trail still exists in the page structure; what you can't do is invent levels that exist nowhere at all.

BreadcrumbList mistakes on deep hierarchies

Docs sites in particular keep tripping over the same five wires:

Leading with the brand name as crumb one instead of Home, then having Home appear again at level two.
Leaving derived slugs unedited, so searchers see V2 and Getting-started with a hyphen in the snippet.
Version segments in the trail pointing at redirecting URLs after a docs migration; crumbs through a 301 chain erode the trail's credibility.
Single-item trails on hub pages, which carry no information and dilute the sitewide pattern.
Restarting numbering per section, so every subsection begins again at position 1 mid-trail.

A working routine for breadcrumb schema at scale

Start every page with Analyze page rather than a blank editor: importing an existing trail, or a path-derived draft, and correcting it is faster and less error prone than typing four names and four URLs. For a docs platform, do this once per template, swap in template variables, and let the generator serve as your reference output.

After deploying, pull two or three of your deepest live pages back through an extractor to confirm the trails render and the names survived the template. Depth is where template bugs hide: a trail that works at three levels can silently truncate at five, and nobody notices because nobody checks the retries page under webhooks under v2.

BreadcrumbList and its companion tools

When a page needs general markup and a short trail together, the WebPage Schema Generator bundles a three level breadcrumb inside a WebPage block, handy for shallow pages that don't justify a standalone list. For anything deeper, the dedicated builder here is the right size.

For verification, the Schema Extractor reads any live URL and returns every JSON-LD block it ships, which makes checking a deployed BreadcrumbList, yours or a competitor's, a ten second job.