Automatically generated breadcrumb markup

[kotryna-k]

Have you read the Contributing Guidelines on issues?

• I have read the Contributing Guidelines on issues.

Description

We'd love to have the possibility to add the breadcrumb markup to all pages automatically. The breadcrumb markup enables Google to see the breadcrumb navigation on the website and display it in search results.

Has this been requested on Canny?

No, it hasn't been requested on Canny yet.

Motivation

We are a team of developers who use docusaurus for the documentation of our product. Our documentation is available to everyone on the internet. It helps new users to get acquainted with our product and dive deeper into its features.

Recently, we have set up breadcrumb navigation across all our documentation. Now we would like to provide Google with information about breadcrumbs so that Google can display it in search results.

What we need is to allow Google to see our breadcrumb navigation on every page of the documentation. As we have about thousands of pages, it looks like an enormous amount of work to add this markup manually. Thus, we’d love to have the possibility to generate it automatically.

API design

Here is an example of the breadcrumb markup:

<script type="application/ld+json">
{
 "@context": "https://schema.org",
 "@type": "BreadcrumbList",
 "itemListElement":
 [
  {
   "@type": "ListItem",
   "position": 1,
   "item":
   {
    "@id": "https://example.com/dresses",
    "name": "Dresses"
    }
  },
  {
   "@type": "ListItem",
  "position": 2,
  "item":
   {
     "@id": "https://example.com/dresses/real",
     "name": "Real Dresses"
   }
  }
 ]
}
</script>

, where:
position - the page’s position in the website structure
id - page link
name - h1 of the page

Please note that the last element of breadcrumb navigation shouldn’t have a link in the markup.
We have consulted the following resources on the breadcrumb markup: https://schema.org/BreadcrumbList and https://developers.google.com/search/docs/advanced/structured-data/breadcrumb.

Have you tried building it?

We haven't tried building it, because implementing such a feature is possible only under the hood of docusaurus.

Self-service

• I'd be willing to contribute this feature to Docusaurus myself.

[Josh-Cena]

Hi, in the latest version, we already have embedded microdata (#6697). We've tested it on the Google Rich Results Test and it achieves the same result as JSON-LD data. Have you tried?

Note we intentionally bias towards microdata rather than JSON-LD. See #5355

[Josh-Cena]

If there are SEO improvements we can make to the current markup, I'm open to re-open this.

[kotryna-k]

If there are SEO improvements we can make to the current markup, I'm open to re-open this.

We would like to suggest an improvement to the current implementation of the breadcrumb markup. Now the @ id field of the last element contains the data from the name field. However, the @ id field should serve to indicate a link to the page. We’d like to point out that the last element of the breadcrumb navigation has no link to any page, as it’s the end of the user’s journey following breadcrumbs. Thus, the @ id field of the last element should be empty.

[Josh-Cena]

I'm also aware of that; however, I'm not aware how to make that ID empty, because we never set it. It's inferred from the href property of the anchor. Do you think not showing the last entry at all would be better for SEO?

[kotryna-k]

Hello Josh,

I am afraid you can't hide the last element of breadcrumb navigation if I understood it right what you meant. If you hide it, then the last visible element would be considered the last element of breadcrumb navigation.

The last element should only contain a value for the name field. Maybe, you can somehow hide just the id field of the last element instead? That might work.

[Josh-Cena]

No, not visually hide it, but not generate the microdata markup for it.

[kotryna-k]

Then the last element of breadcrumb navigation for Google will be the last element, for which there is generated microdata in the markup. It will result in incorrect display of breadcrumbs in search results, as they won't include the last page where a user can navigate to. Besides, I can't see how it will solve the issue with the id field.

[Josh-Cena]

If you look at our microdata, it looks something like:

<ul itemscope="" itemtype="https://schema.org/BreadcrumbList">
  <li><a href="/">🏠</a></li>
  <li itemscope="" itemprop="itemListElement" itemtype="https://schema.org/ListItem">
    <a itemprop="item" href="/docs/category/guides"><span itemprop="name">Guides</span></a>
    <meta itemprop="position" content="1">
  </li>
  <li itemscope="" itemprop="itemListElement" itemtype="https://schema.org/ListItem">
    <a itemprop="item" href="/docs/docs-introduction"><span itemprop="name">Docs</span></a>
    <meta itemprop="position" content="2">
  </li>
  <li itemscope="" itemprop="itemListElement" itemtype="https://schema.org/ListItem">
    <a itemprop="item" href="/docs/sidebar"><span itemprop="name">Sidebar</span></a>
    <meta itemprop="position" content="3">
  </li>
  <li itemscope="" itemprop="itemListElement" itemtype="https://schema.org/ListItem">
    <span itemprop="item name">Autogenerated</span><meta itemprop="position" content="4">
  </li>
</ul>

We didn't provide the id field. The id field comes from the href of the <a> element.

However, I've just found a way to fix it. Will send a PR.

[slorber]

Please note that the last element of breadcrumb navigation shouldn’t have a link in the markup.
We have consulted the following resources on the breadcrumb markup: schema.org/BreadcrumbList and developers.google.com/search/docs/advanced/structured-data/breadcrumb.

Are you sure this is supposed to be the correct behavior?

Because there is a link on this page 🤪

[Josh-Cena]

@slorber When I implemented it, I've seen people arguing both ways. The consensus is that while a link on the page doesn't matter, an id in the structured data (which is synonymous to href) is probably not worth adding.

[slorber]

I find it weird to not have a link on the last item (although it's not really useful to link to self). Have you seen this pattern in other breadcrumbs?

I like the idea to have a link on each breadcrumb item personally (although I understand some categories might not have a link/page)

Can't we keep the link and drop the id? How other sites using breadcrumbs doing?

[Josh-Cena]

Here's Google's docs: https://developers.google.com/search/docs/advanced/structured-data/breadcrumb#year-genre%20example Note their last item has a different markup (no item, only name)

[slorber]

That's not what I see in practice in their own site:

Check this page for example: https://developers.google.com/search/docs/advanced/structured-data/carousel

=> They have item + name on the last item + linking to the current page

=> The displayed breadcrumb does not even match the json+ld breadcrumb

[Josh-Cena]

That's interesting. Note that using JSON-LD means you can decouple structured data from markup which we cannot, but I don't think that's very critical (and I think you can agree; we just need some sensible default).

Now about the last part of the breadcrumb list having the link. The end result seems the same:

Neither ours nor theirs actually display the last part of the breadcrumbs list in the search result. Furthermore, the fact that Google's docs don't include it at least indicates that they are smart enough to understand that the last item is the current page.

Just as a reminder, prior to this issue, our last item is already not associated with a link (#6932). Making the structured data contain a link will be confusing anyways.

[slorber]

ok 👍 we can keep it this way and see if anyone complains 🤪