Experiment with collapsed ToC categories

[jmacdotorg]

Now that we've reorganized the table of contents categories, I hypothesize that starting out a new visit visit to the docs website will all the categories collapsed (except the one containing the page that you landed on) would make them much easier to navigate, with a lot less cognitive load on the reader.

Let's stage an experiment of this and see how it looks.

[linear]

ENG-1383 Experiment with collapsed ToC categories

[traycerai]

Plan

Observations

• The project runs on Docusaurus v3.6.1 with no existing shadow for DocSidebarItem/Category.
• Categories are defined in sidebars.ts (or _category_.yaml) with collapsible and collapsed props.
• By default, the Category component auto-expands if it contains the active page via internal route checks.
• The useCollapsible hook drives open/closed state via an initialOpen boolean.
• Feature flags must be injected via themeConfig and accessed through useDocusaurusContext.

Approach

1. Define a new collapsedTocCategories flag under themeConfig.features in docusaurus.config.ts.
2. Shadow the default Category by creating src/theme/DocSidebarItem/Category/index.tsx.
3. Copy the original code and import useDocusaurusContext, the active-item util (isActiveSidebarItem), and useCollapsible.
4. Read collapsedTocCategories from the site config and compute hasActiveChild by re-using the original active-detection logic.
5. Call useCollapsible({ initialOpen: collapsedTocCategories ? hasActiveChild : defaultCollapsed }) instead of the static default.
6. Leave all other JSX, toggle handlers, and CSS classes intact for seamless integration.

Reasoning

We audited the codebase to confirm Docusaurus v3.6.1, no existing overrides, and the mechanism for feature flags. We inspected the default Category component’s collapse logic and the useCollapsible hook. With a clear path to shadow the component and gate the new behavior behind a config flag, we can implement the experimental “collapsed by default” UX without touching sidebars.ts or YAML metadata.

Proposed File Changes

📄 docusaurus.config.ts ^(MODIFY) 🔗

References

• 📄 docusaurus.config.ts ^(MODIFY)

In the themeConfig section of docusaurus.config.ts, locate or create a features object. Add a new flag called collapsedTocCategories: true to enable the experiment. For example:

// In docusaurus.config.ts
export default {
  // … existing config …
  themeConfig: {
    // … other settings …
    features: {
      // … existing flags …
      collapsedTocCategories: true,
    },
  },
};

📁 src/theme/DocSidebarItem/Category ^(NEW) 🔗

Create a directory at src/theme/DocSidebarItem/Category to shadow the default theme component.

📄 src/theme/DocSidebarItem/Category/index.tsx ^(NEW) 🔗

References

• 📄 docusaurus.config.ts ^(MODIFY)

Create index.tsx by copying the default implementation from @docusaurus/theme-classic/lib/theme/DocSidebarItem/Category. Then:

1. Import useDocusaurusContext from @docusaurus/core.
2. Import the same isActiveSidebarItem utility used in the original to check if an item or descendant matches the current route.
3. Destructure props to obtain items and the original collapsed prop (call it defaultCollapsed).
4. Read collapsedTocCategories via const { siteConfig } = useDocusaurusContext();
5. Compute hasActiveChild = items.some(item => isActiveSidebarItem(item, activePermalinkFromContext));
6. Replace the original useCollapsible({ initialOpen: defaultCollapsed }) call with:

   useCollapsible({ initialOpen: collapsedTocCategories ? hasActiveChild : defaultCollapsed })

7. Keep all other JSX structure, toggle logic, and CSS classes exactly as in the default component.

This override collapses all categories on initial load, except the branch containing the active page when the experiment flag is enabled.

Diagram

sequenceDiagram
    participant Browser
    participant CategoryOverride as Category (override)
    participant Context as useDocusaurusContext
    participant Collapsible as useCollapsible

    Browser->>CategoryOverride: Mount each category
    CategoryOverride->>Context: Read collapsedTocCategories flag
    CategoryOverride->>CategoryOverride: Compute hasActiveChild via isActiveSidebarItem
    CategoryOverride->>Collapsible: initialOpen = flag ? hasActiveChild : defaultCollapsed
    Collapsible-->>CategoryOverride: Provide open, toggle, props
    CategoryOverride-->>Browser: Render collapsed/expanded sidebar UI

Loading

Import In IDE

Developer Humor

“Why did the sidebar categories go to therapy?
They were tired of always being expanded—until they found their inner collapse! 🤓
Now only the relevant branch opens, and everyone’s happier.
🗂️✨
— Sidebar Support Hotline

---

Execution Information

Branch: main
Commit: cfaef41

---

💡 Tips

Supported Commands (Inside Comments)

• Use @traycerai generate to iterate on the previous version of the implementation plan.

Supported Commands (Inside Description)

• Add @traycerai ignore anywhere in the ticket description to prevent this ticket from being processed.
• Add @traycerai branch:<branch-name> anywhere in the ticket description to specify the target branch for the implementation plan.

Community

• Join our Discord Community to get help, request features, and share feedback.
• Follow us on X/Twitter for updates and announcements.