fix(theme-classic): include top-level breadcrumb in structured data (…

[1012ayush]

…fixes #12208)

Pre-flight checklist

• I have read the Contributing Guidelines on pull requests.
• If this is a code change: I have written unit tests and/or added dogfooding pages to fully verify the new behavior.
• If this is a new API or substantial change: the PR has an accompanying issue (closes #0000) and the maintainers have approved on my working plan.

Motivation

This PR addresses issue #12208. Previously, the structured data (JSON-LD) for documentation breadcrumbs was filtering out top-level categories that lacked an href. This created a discrepancy where the visual breadcrumbs were complete, but the SEO metadata was missing the top-level parent category. This change updates the mapping logic to ensure all breadcrumb levels are included in the JSON-LD output, while maintaining valid schema structure.

Test Plan

I verified this fix through the following steps:

Code Modification: Updated the useBreadcrumbsStructuredData hook in packages/docusaurus-plugin-content-docs/src/client/structuredDataUtils.ts.

Logic Update: Replaced the .filter() method (which excluded items without an href) with a conditional spread operator. This ensures that every breadcrumb item is mapped to a ListItem, and the item (URL) property is only added if an href exists.

Verification: Inspected the generated <script type="application/ld+json"> tag in browser developer tools on a local documentation page to confirm the top-level category is now correctly included.

Related issues/PRs

Fixes #12208

[meta-cla]

Hi @1012ayush!

Thank you for your pull request and welcome to our community.

Action Required

In order to merge any pull request (code, docs, etc.), we require contributors to sign our Contributor License Agreement, and we don't seem to have one on file for you.

Process

In order for us to review and merge your suggested changes, please sign at https://code.facebook.com/cla. If you are contributing on behalf of someone else (eg your employer), the individual CLA may not be sufficient and your employer may need to sign the corporate CLA.

Once the CLA is signed, our tooling will perform checks and validations. Afterwards, the pull request will be tagged with CLA signed. The tagging process may take up to 1 hour after signing. Please give it that time before contacting us about it.

If you have received this in error or have any questions, please contact us at cla@meta.com. Thanks!

[netlify]

✅ [V2]

Built without sensitive environment variables

Name	Link
🔨 Latest commit	813f361
🔍 Latest deploy log	https://app.netlify.com/projects/docusaurus-2/deploys/6a46d9a4a42bc500080d1ed1
😎 Deploy Preview	https://deploy-preview-12222--docusaurus-2.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[meta-cla]

Thank you for signing our Contributor License Agreement. We can now accept your code for this (and any) Meta Open Source project. Thanks!

[meta-cla]

Thank you for signing our Contributor License Agreement. We can now accept your code for this (and any) Meta Open Source project. Thanks!

[slorber]

I understand why you want to do this, but we deliberately choose to filter these breadcrumb items

I'm using this example as a reference for tests: https://deploy-preview-12222--docusaurus-2.netlify.app/tests/docs/tests/ascii/folder/%C3%A6%C3%B8%C3%A5

• Google rich result validator still returns errors for breadcrumb items without any URL: https://search.google.com/test/rich-results/result/r%2Fbreadcrumbs?id=Gx2SkEQjMjsTCHtzSaanhw

• However, Schema.org validator passes: https://validator.schema.org/#url=https%3A%2F%2Fdeploy-preview-12222--docusaurus-2.netlify.app%2Ftests%2Fdocs%2Ftests%2Fascii%2Ffolder%2F%25C3%25A6%25C3%25B8%25C3%25A5

If you can find a decent solution where both validators pass, I'll accept the PR

---

See the errors:

[1012ayush]

Hi @slorber, thanks for taking the time to review and for providing the clear screenshot!

You're completely right. I see exactly what is happening: Schema.org is flexible enough to accept a ListItem without an item (URL) property, but Google's Rich Results validator strictly mandates it (throwing the Champ 'item' manquant error).

Since the goal is to get both validators to pass while still representing the full category tree in the SEO metadata, we have to provide Google with some valid URL string for those unlinked categories.

Here are a two potential fallback strategies to satisfy Google's validator. Let me know which one you feel best aligns with Docusaurus's architecture:

Option 1: Use a hash fragment as a fallback
If a category doesn't have an href, we can pass the current page's URL appended with a hash of the category name (e.g., item: breadcrumb.href || '${currentUrl}#${breadcrumb.label}'). This gives Google the valid URL string it demands without creating 404 links.
Option 2: Point to the site's base URL
We could simply fallback to the baseUrl (e.g., /) for any unlinked category item. It satisfies the schema requirement, though it's slightly less semantically precise than Option 1.
Do either of these sound like a decent solution to you, or is there another fallback strategy you'd prefer I implement? I'd be happy to update the PR!

[slorber]

I don't think any of these strategies are good.
If we implement something, I'd like an authoritative source (like... Google) to explain why it's a good solution/workaround. The goal is not just to make the Google validator pass, but also to have structured data that is consistent with what Google expects.

[1012ayush]

Hi @slorber, thank you for the feedback. I’ve reviewed the Google Search Central Breadcrumb documentation and I see the issue: the item property is strictly required for non-terminal breadcrumbs. My previous approach was incorrectly trying to include items that lacked a URL, which violates Google’s requirements.

I agree that filtering them out is the correct way to maintain schema compliance. Since I now understand the strict constraints around ListItem data integrity. Moving forward, I’m exploring whether we can architecturally support 'index' pages for categories so that every breadcrumb level has a valid URL, which would allow us to include them in the schema legitimately.

I'll keep this requirement in mind for future improvements.