Allow manual sidebars to automatically pick up category indexes

[ZenaMel]

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

I've run into an issue with index markdown files and manually managed sidebars.

Expected:

given sidebars.js

/** @type {import('@docusaurus/plugin-content-docs').SidebarsConfig} */
const sidebars = {
  controllerFirmwareSidebar: [
    'index',
    {
      Configuration: [
        'Configuration/index',
      ],
    },
  ],
};

Clicking on "Configuration" in the sidebar should automatically show the content of the index file like illustrated in the official documentation. This works as expected for the top level.

Am I missing something obvious? Perhaps the documentation is just unclear on how to work with the index files in a manual sidebar context. From what I can tell, Docusaurus' documentation uses manual sidebars and has no problems following the index.mdx convention.

Reproducible demo

No response

Steps to reproduce

1. Create a starter docusaurus with the standard steps as seen in the official documentation.
2. Set up a file an folder structure that follows the sidebar config shown above.
3. Click on the Configuration in the sidebar.

Expected behavior

Immediately show the index.mdx content.

Actual behavior

Expands category and shows index in sidebar.

Your environment

No response

Self-service

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

[ZenaMel]

The current workaround seems to be

/**
 * Creating a sidebar enables you to:
 - create an ordered group of docs
 - render a sidebar for each doc of that group
 - provide next/previous navigation

 The sidebars can be generated from the filesystem, or explicitly defined here.

 Create as many sidebars as you want.
 */

// @ts-check

/** @type {import('@docusaurus/plugin-content-docs').SidebarsConfig} */
const sidebars = {
  controllerFirmwareSidebar: [
    'index',
    {
      type: 'category',
      label: 'Configuration',
      link: {
        type: 'doc',
        id: 'Configuration/index',
      },
      items: [
        'Configuration/introduction',
      ],
    },
  ],
};

module.exports = sidebars;

Something like

/**
 * Creating a sidebar enables you to:
 - create an ordered group of docs
 - render a sidebar for each doc of that group
 - provide next/previous navigation

 The sidebars can be generated from the filesystem, or explicitly defined here.

 Create as many sidebars as you want.
 */

// @ts-check

/** @type {import('@docusaurus/plugin-content-docs').SidebarsConfig} */
const sidebars = {
  controllerFirmwareSidebar: [
    'index',
    {
      Configuration: [
        'Configuration/index',
      ],
    },
  ],
};

module.exports = sidebars;

Or even an opt-in feature for manual sidebars, something like respectIndexFilesInCategories as a global configuration inside the main config file would be great IMO.

Based on that, if set to true, manual sidebars won't have to specify index.md(x) files, rather the standard convention would take effect that is already in place for autogenerated sidebars.

[Josh-Cena]

Your "workaround" is currently the only way to do it, yes. The category shorthand has a range of limitations, including the inability to specify any extra metadata such as label, collapsibility, or the index link. To add any of these, you would need to expand it to its full form. We can keep it open to gather more feedback about the respectIndexFilesInCategories option.

[slorber]

/** @type {import(https://github.com/facebook/docusaurus/tree/master/packages/docusaurus-plugin-content-docs).SidebarsConfig} */
const sidebars = {
  controllerFirmwareSidebar: [
    'index',
    {
      Configuration: [
        'Configuration/index',
      ],
    },
  ],
};

I don't know if we want to support inferring a doc is the index based on its name for explicit (non-auto-generated) category trees. That's not very explicit.

What if your index doc is in the middle or the end of the list, do you still expect it to be the category index?

[ZenaMel]

/** @type {import(https://github.com/facebook/docusaurus/tree/master/packages/docusaurus-plugin-content-docs).SidebarsConfig} */
const sidebars = {
  controllerFirmwareSidebar: [
    'index',
    {
      Configuration: [
        'Configuration/index',
      ],
    },
  ],
};

I don't know if we want to support inferring a doc is the index based on its name for explicit (non-auto-generated) category trees. That's not very explicit.

What if your index doc is in the middle or the end of the list, do you still expect it to be the category index?

That's definitely a way to look at it. The way I see this is if we support this with a global config option we do make it somewhat explicit.

Nonetheless, it would be nice if we could at least use index files in manual sidebars with shorthand notation. I don't see why we'd want to only allow that with verbose syntax only.

Another option to make this more explicit could be moving the useIndexFiles as an option to the sidebars.js files instead of having it as a global option.

Would that make this explicit enough?

Again, I think the main point would really be to allow using index files in shorthand notation for manual sidebars. Just that would be great.

[slorber]

I'd rather avoid adding too many niche options. Using the shorthand notation is for simple case, and it's expected to move to the object notation when you need something more advanced.

What happens if you have this? Which doc becomes the index? 🤷‍♂️

/** @type {import(https://github.com/facebook/docusaurus/tree/master/packages/docusaurus-plugin-content-docs).SidebarsConfig} */
const sidebars = {
  controllerFirmwareSidebar: [
    {
      Configuration: [
        "Configuration/doc1",
        "Configuration/readme",
        "readme",
	    "doc2",
        "Configuration",
        "doc3",
        "Configuration/index",
        "index"
        "doc4",
      ]
    }
  ]
};

To me, this is not a very intuitive behavior and a potential source of confusion. Even more confusing, a file can be index.md but the id might not be "index" if defined explicitly. I'd rather have a new frontMatter index: true and even that does not feel so great to me due to possibly multiple md files having a "true" value.