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 as a raw URL it tells a searcher little. A breadcrumb trail, Docs to API to Webhooks, reads far better, and BreadcrumbList markup is how you give Google your own labels for it. Since January 2025 Google shows breadcrumbs in desktop results only. This guide covers the position rules, a worked example from a fictional docs site, doing many pages at once, and the mismatches that make Google ignore your trail.

Open the free Breadcrumb Schema Generator All insights

How breadcrumb trails get into search results

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 V2, and api stays a slug fragment. BreadcrumbList markup replaces the guesswork with your own labels, so desktop results read API Reference instead.

The benefit grows with depth. A three-level marketing site barely notices; a documentation portal where every meaningful page sits four or more levels down gains readable trails across its whole long tail. There's a second audience too: the trail states your site structure as explicit parent and child relationships, which helps crawlers place deep pages in the right section.

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. When a page has no breadcrumb markup, Analyze page builds a draft from the path, turning each folder into a capitalised name, and existing BreadcrumbList markup is imported for editing instead. The renaming step is where derived trails become good trails.

Breadcrumb position rules that matter

The rules are strict and short. Positions are integers starting at 1, sequential, with no gaps or repeats, ordered from the top of the site down to the current page. Each ListItem carries a name, and every level except the last needs an item URL pointing at a live, indexable page.

Google allows the last level, the current page, to leave out its URL, and the generator lets you do the same; it warns about and leaves out any earlier level that has no URL. What Google won't accept is a trail running backwards, current page first, a surprisingly common hand-coding inversion. The tool renumbers positions whenever you reorder, add or delete a level.

Matching visible breadcrumbs to the markup

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, not a five-level hierarchy the reader never sees. Divergence tells Google one of the two is wrong.

This cuts against a common temptation on deep sites: shortening the visible trail for design reasons while keeping the full path in the markup. Shorten both or neither. If the design hides middle levels behind an ellipsis on mobile, that's fine, since the full trail still exists in the page; what you can't do is invent levels that exist nowhere. A page that genuinely belongs to two paths, such as a product in two categories, can carry two separate trails.

BreadcrumbList mistakes on deep hierarchies

Docs sites in particular keep making the same five mistakes:

Leading with the brand name as crumb one instead of Home, then having Home appear again at level two.
Leaving derived names unedited, so the trail shows V2 or a slug-style label instead of your navigation's wording.
Version segments pointing at redirecting URLs after a docs migration; every folder URL in the trail should be a real page, not a redirect or a 404.
Single-item trails on hub pages, which carry no information.
Restarting numbering per section, so a subsection begins again at position 1 mid-trail.

Breadcrumb markup at scale

For one page, start with Analyze page rather than a blank editor: importing an existing trail, or a path-derived draft, and correcting it is faster than typing four names and four URLs. For many pages, open Bulk (many URLs), paste up to 500 URLs one per line and set the name for the first level. Each URL gets its own BreadcrumbList built from its path, without fetching anything, ready to copy one by one or save with Download all. It's the quick way to restore markup after a CMS migration drops it across a whole section.

Output can be JSON-LD or Microdata. Microdata has to wrap your visible breadcrumb links, so it takes more template work; Google recommends JSON-LD. After deploying, pull two or three of your deepest live pages through the Schema Markup Extractor to confirm the trails render and the names survived the template. Depth is where template bugs hide.

BreadcrumbList and its companion tools

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

For checking, the Schema Markup Extractor reads any live URL and lists every JSON-LD, microdata and RDFa item it serves, which makes verifying a deployed BreadcrumbList, yours or a competitor's, quick work.