fix(docs): breadcrumb APIs only return category/docs items, ignoring links

[Chesars]

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 generated-index page shows parent category items when linked from another category #11612) and the maintainers have approved on my working plan.

Motivation

Fixes #11612

When a sidebar link in one category points to a generated-index page URL from another category, Docusaurus incorrectly renders the page using items from the link's origin category instead of the target category's actual items.

Example:

• Category A has docs (doc1, doc2) and a link pointing to /docs/category-b
• Category B has a generated-index at /category-b containing items (item1, item2, item3)

/docs/category-b displays cards for item1, item2, item3
(bug): The page displays cards for doc1, doc2 from Category A

getSidebarBreadcrumbs() does a depth-first search that returns on the first match. If Category A appears before Category B in the sidebar, it finds the link in Category A first and returns Category A as the "owner" of the URL.

Solution

Use a two-pass approach when onlyCategories: true (used by useCurrentSidebarCategory()):

1. Look for categories that directly own the URL (category.href === pathname)
2. If not found, fall back to finding via links (to support doc pages)

This ensures generated-index pages display their correct category's items, while maintaining backwards compatibility for regular doc pages.

Test Plan

Added a regression test in docsUtils.test.tsx that verifies:

• When Category A has a link pointing to Category B's URL
• And Category B has href set to that URL (via generated-index)
• useCurrentSidebarCategory() returns Category B (the owner), not Category A

Related issues/PRs

Closes #11612

[meta-cla]

Hi @Chesars!

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 [email protected]. Thanks!

[netlify]

✅ [V2]

Name	Link
🔨 Latest commit	76ae622
🔍 Latest deploy log	https://app.netlify.com/projects/docusaurus-2/deploys/694968441802e6000893828d
😎 Deploy Preview	https://deploy-preview-11616--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!

[argos-ci]

The latest updates on your projects. Learn more about Argos notifications ↗︎

Build	Status	Details	Updated (UTC)
default (Inspect)	✅ No changes detected	-	Dec 22, 2025, 4:02 PM

[slorber]

Thanks for catching this bug.

Your code seems to work, however I think it also makes sense to always favor category href over link href even for the regular breadcrumb case, so I reworked/simplified the logic and added an extra test for it.

To be honest, I'm not even sure we need this 2-pass approach. Is there any good reason to show a link item in a breadcrumb?

For now let's be conservative, but I think in #8008 and #6517 we may have added tests for something that shouldn't be supported in the first place?

[slorber]

Yeah so it turns ouf that the 2-pass approach wouldn't completely solve the problem: this only works if your link targets a category, but there's another edge case to consider: linking to a doc.

After looking at the history (#6517) at the time this was implemented, there was no way on the frontend to distinguish between a doc link (sidebar item type doc) from a regular link (sidebar item type link). Now that we coan make that distinction, we can simply ignore the items that are not associated to a doc, because I see no good reason for a non-doc link to appear in a breadcrumb.