Index of doc category unreachable when a document of the category is displayed

[lebalz]

Have you read the Contributing Guidelines on issues?

• [x] I have read the Contributing Guidelines on issues.

Prerequisites

• [x] I'm using the latest version of Docusaurus.
• [x] I have tried the npm run clear or yarn clear command.
• [x] I have tried rm -rf node_modules yarn.lock package-lock.json and re-installing packages.
• [x] I have tried creating a repro with https://new.docusaurus.io.
• [x] I have read the console error message carefully (if applicable).

Description

#10886 enhanced the way active sidebar categories can be expanded and collapsed. But this introduced an unexpected UX - when inside a category, there is no way to open a parent category index page in the same path (this is true for all predecessor index pages).

https://github.com/user-attachments/assets/4a7a09d6-39ce-49bb-beda-c04e32274348

Reproducible demo

No response

Steps to reproduce

1. Open a document category over the sidebar, e.g. https://docusaurus.io/docs/sidebar
2. Navigate to a doc from this category, e.g. https://docusaurus.io/docs/sidebar/items
3. Try to display the index page of the category by clicking on the category - the category collapses, but does not display it's content.

Expected behavior

I would expect the category index page to be displayed when i click on the sidebar link.

Actual behavior

The category index page opens only, when not within this category. When within this category, it toggles the visible/collapsed state.

Your environment

• Public source code:
• Public site URL:
• Docusaurus version used:
• Environment name and version (e.g. Chrome 89, Node.js 16.4):
• Operating system and version (e.g. Ubuntu 20.04.2 LTS):

Self-service

• [ ] I'd be willing to fix this bug myself.

[Josh-Cena]

TBH I preferred the previous behavior: a category cannot be collapsed by clicking on the link, unless you explicitly request it to be closed via the caret...

[tjsturos]

This should be fixed, as this is relatively important if you have important category content on the index page.

[tjsturos]

For now my workaround is to override the theme by creating src/theme/DocSidebarItem/Category/index.tsx and pasting the file found in https://github.com/GBSL-Informatik/teaching-dev/blob/main/src/theme/DocSidebarItem/Category/index.tsx

Then recompiling/restarting the dev server.

[pranabdas]

1. I think, the navigation issue should be treated as a bug. Currently, when viewing pages under a specific category, the category index page becomes inaccessible, which should be addressed.
2. Secondly, I would opt for the previous collapsing behavior. While browsing within a category, collapsing it should have the least priority. Therefore, using the chevron button to explicitly collapse categories makes more sense.

[postpuber]

I can confirm this exact issue after upgrading from 3.7 to 3.8. The navigation on my doc website became too complicated and illogical for users.

My setup: Autogenerated sidebars with category folders containing index.mdx files that serve as overview/landing pages.

Users can no longer navigate to category index pages when they're already viewing content within that category. This breaks the fundamental navigation pattern where category names should be clickable links to provide context and overview.

Had to downgrade back to 3.7. This is a significant UX regression that affects the core navigation patterns. Hope this gets prioritized for a quick fix 🙏

[kubaprzetakiewicz]

yes, being able to collapse a category that has an index page by clicking on its label is indeed very weird, especially that there is a caret right next to it

[slorber]

Yes I also noticed a problem.

Will look into fixing the issue while preserving the behavior implemented for https://github.com/facebook/docusaurus/issues/10854

It will be fixed in an upcoming v3.8 patch

[slorber]

TBH I preferred the previous behavior: a category cannot be collapsed by clicking on the link, unless you explicitly request it to be closed via the caret...

@Josh-Cena then what do you expect to happen if you click on the category label/link?

Why would you click it in the first place, considering you are already on the category's page?

If you don't expect to collapse, then you expect it to do nothing, and you don't do the action.

The problem to me is that we don't navigate if a category's child is active, which prevents us from navigating from a child page to its parent category's page. But collapsing the category if we are on that category's page should be ok and not be confusing, because it's the only thing you can expect from that action.

[Josh-Cena]

For me, I expect two invariants:

1. Clicking on a link takes me to that page, including when I'm already on that page
2. When I navigate to a page, all its parent categories are expanded in the sidebar

Given both of these, I would expect:

1. Clicking on an open category index X while already viewing X should go to X and expand X, i.e. do nothing
2. Clicking on a closed category index X while already viewing X should go to X and expand X, i.e. expand X only
3. Clicking on an open category index X while viewing Y should go to X and expand X, i.e. just go to X
4. Clicking on a closed category index X while viewing Y should go to X and expand X

With your revised UX, we are making a special case for 1, but making it inconsistent with 3 and 4

[pranabdas]

I think toggling the expand/collapse is not a bad idea when we are already on the category index page. I guess when we click, we expect something to happen. Since we are already on the page, we may toggle expand/collapse. When we are not in the category index page, clicking should take me there and expand it (or keep it expanded if already expanded).

[slorber]

The behavior should be fixed in https://github.com/facebook/docusaurus/pull/11242

Please test it here and let me know if you find it confusing, because I'm going to release this quite soon:

https://deploy-preview-11242--docusaurus-2.netlify.app/docs/markdown-features/react

Click on any parent category (Guide / Markdown Features): it should navigate to it.

It will only collapse the category if you click a second time, which is not unusual, and is to me the only reasonable thing to do.

See also the original issue: https://github.com/facebook/docusaurus/issues/10854#issuecomment-2609616182

This behavior is also implemented in:

• Nextra: https://nextra.site/docs/docs-theme/built-ins/layout (apparently fixed the unwanted collapsing behavior I mention in the issue)
• Fumadocs: https://fumadocs.dev/docs/ui/markdown/math

[slorber]

1. Clicking on a link takes me to that page, including when I'm already on that page

If you are already on /docs/category, and you click on that category's item, what does it even mean to "take you to that page"? We are going to do nothing because we are already on that page, we don't even want to create a new history entry for that.

1. Clicking on an open category index X while already viewing X should go to X and expand X, i.e. do nothing With your revised UX, we are making a special case for 1, but making it inconsistent with 3 and 4

Yes, but I believe it's better and the only reasonable action to take if you click on a link you already browse, because otherwise we could simply ignore the click (or eventually open the category if it has been explicitly closed with the caret icon). This is what other modern docs framework implement, and has been requested, so I think it's fine to keep it and actually a nice UX improvement.

[slorber]

Fixed in v3.8.1: https://github.com/facebook/docusaurus/releases/tag/v3.8.1