fix(seo): docs breadcrumb structured data should use JSON-LD and filter unliked categories (#10888)

Co-authored-by: sebastien <lorber.sebastien@gmail.com>

packages/docusaurus-plugin-content-docs/package.json

@@ -49,6 +49,7 @@
     "fs-extra": "^11.1.1",
     "js-yaml": "^4.1.0",
     "lodash": "^4.17.21",
+    "schema-dts": "^1.1.2",
     "tslib": "^2.6.0",
     "utility-types": "^3.10.0",
     "webpack": "^5.88.1"

packages/docusaurus-plugin-content-docs/src/client/index.ts

@@ -60,6 +60,8 @@ export {
   getDocsVersionSearchTag,
 } from './docsSearch';
 
+export {useBreadcrumbsStructuredData} from './structuredDataUtils';
+
 export type ActivePlugin = {
   pluginId: string;
   pluginData: GlobalPluginData;

packages/docusaurus-plugin-content-docs/src/client/structuredDataUtils.ts

@@ -0,0 +1,32 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+import useDocusaurusContext from '@docusaurus/useDocusaurusContext';
+import type {PropSidebarBreadcrumbsItem} from '@docusaurus/plugin-content-docs';
+import type {WithContext, BreadcrumbList} from 'schema-dts';
+
+export function useBreadcrumbsStructuredData({
+  breadcrumbs,
+}: {
+  breadcrumbs: PropSidebarBreadcrumbsItem[];
+}): WithContext<BreadcrumbList> {
+  const {siteConfig} = useDocusaurusContext();
+  return {
+    '@context': 'https://schema.org',
+    '@type': 'BreadcrumbList',
+    itemListElement: breadcrumbs
+      // We filter breadcrumb items without links, they are not allowed
+      // See also https://github.com/facebook/docusaurus/issues/9319#issuecomment-2643560845
+      .filter((breadcrumb) => breadcrumb.href)
+      .map((breadcrumb, index) => ({
+        '@type': 'ListItem',
+        position: index + 1,
+        name: breadcrumb.label,
+        item: `${siteConfig.url}${breadcrumb.href}`,
+      })),
+  };
+}