Breadcrumb markup for a docs site: required fields and mistakes

Breadcrumb markup tells Google where a page sits in your hierarchy. Use a BreadcrumbList with at least two ListItem entries, each with a position and a name, and a URL for every item except the current page. Build the trail around how people navigate, not around the folder structure.

What Google requires

According to Google's documentation, the container is BreadcrumbList, and it must hold at least two ListItem entries in itemListElement. Each ListItem has:

• item: the page URL. It can be omitted for the last item, and Google then uses the current page.
• name: the label users see.
• position: an integer starting at 1.

Google says breadcrumb results appear on desktop in all regions and languages where Search is available. Treat appearance as possible, not promised.

An example for a docs page

{
  "@context": "https://schema.org",
  "@type": "BreadcrumbList",
  "itemListElement": [
    {
      "@type": "ListItem",
      "position": 1,
      "name": "Docs",
      "item": "https://example.com/docs"
    },
    {
      "@type": "ListItem",
      "position": 2,
      "name": "CLI",
      "item": "https://example.com/docs/cli"
    },
    {
      "@type": "ListItem",
      "position": 3,
      "name": "Exit codes"
    }
  ]
}

URLs are placeholders.

Choose the trail honestly

Google says to build breadcrumbs around a typical user path rather than copying the URL structure, and says including the home page or the current page is not required. A docs page may be reachable by several routes. Google notes a page can include multiple trails when several navigation paths lead to the same content.

For versioned docs, the trail should reflect the version a reader is in, and the canonical URL should be consistent. See canonical URLs for versioned docs.

Match the visible trail

The visible breadcrumb on the page and the markup should say the same thing. Generate both from one navigation source. If they diverge, you have markup describing something the reader cannot see, which Google's general guidelines warn against.

Common mistakes

• Only one ListItem, which does not meet the minimum.
• Positions that skip or repeat.
• Relative URLs. Use full URLs.
• Names that differ from the visible labels.
• Old data-vocabulary.org markup, which Google says is no longer eligible.

Test

Run the Rich Results Test on one page per template, then watch Search Console after releases.

Quick check

Sources

• Breadcrumb structured data, Google Search Central
• Introduction to structured data, Google Search Central

Last reviewed: 19 October 2026.