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 🤪