Exclude files in autogenerated (e.g. exclude index page of parent category)

[XomegaNet]

Have you read the Contributing Guidelines on issues?

• I have read the Contributing Guidelines on issues.

Prerequisites

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

Description

When you use a link of type 'doc' in a 'category' sidebar item, which is the default document when you click on that category, it does not hide the linked document inside that category.

  tutorialSidebar: [
    'intro',
    {
      type: 'category',
      label: 'Tutorial Basics',
      link: {type: 'doc', id: 'tutorial-basics/create-a-page'},
      items: [{type: 'autogenerated', dirName: 'tutorial-basics'}],
    },
  ],

If you use autogenerated directory structure though, and set up such a default link inside the _category.json, then it does hide the default document under that category.

{
  "label": "Tutorial - Basics",
  "position": 2,
  "link": { "type": "doc", "id": "create-a-page" }
}

Steps to reproduce

1. Create a new website using npx create-docusaurus@latest website classic
2. Update sidebars.js to use the following sidebar

   tutorialSidebar: [
    'intro',
    {
      type: 'category',
      label: 'Tutorial Basics',
      link: {type: 'doc', id: 'tutorial-basics/create-a-page'},
      items: [{type: 'autogenerated', dirName: 'tutorial-basics'}],
    },
  ],

3. Launch the website using yarn start.
4. Navigate to Tutorial nav menu.

Expected behavior

The Create a Page item should be hidden under the Tutorial Basic category.

Actual behavior

The Create a Page item is visible under the Tutorial Basic category.

Your environment

• Public source code:
• Public site URL: https://xomega.net/docs
• Docusaurus version used: 2.0.0-beta.13
• Environment name and version (e.g. Chrome 89, Node.js 16.4):
• Operating system and version (e.g. Ubuntu 20.04.2 LTS):

Reproducible demo

No response

Self-service

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

[Josh-Cena]

I personally think that falls in the gray area of what's a bug and what's an enhancement, but it's surely something we can improve on. By theory (and also pragmatically how we implemented it), parent items can't alter the subitem's behavior, so when you added an index for the parent category, the autogenerated subitem doesn't know about that change and would collect its own items independently.

[XomegaNet]

so, why does it hide the child item, if you specify the link in the _category.json then? We noticed that behavior after these links were introduced lately, which is what we prefer, by the way, but then it was behaving differently if you don't use autogenerated sidebars, and specify the 'category' items explicitly.

If this is not a bug, is there any workaround to achieve this behavior, i.e. hide the default item for the category when the latter is not autogenerated?

[Josh-Cena]

There isn't a good workaround (see also #5689), and if it works by adding the doc to _category_.json then great, you found a workaround. A _category_.json works in joint with the actual autogenerated item, so the autogenerated item does respect what's in that file. On the other hand, the category item is a parent item of autogenerated, so autogenerated works on its own, collects its children, and populates the items field of category with those items. It doesn't know anything about its parent item (at least for now; we are willing to properly address this issue)

[XomegaNet]

Ok, just to be clear, if I create a default website using npx create-docusaurus@latest website classic, and then add a link to the tutorial-basics/_category.json file as follows

{
  "label": "Tutorial - Basics",
  "position": 2,
  "link": {
    "type": "doc",
    "id": "create-a-page"
  }
}

then clicking on the Tutorial - Basics link in the running website will show the Create a Page page, which will not be shown in the sidebar, which is what we want. But (!), this only works as long as I use the default autogenerated sidebar for the entire docs folder, i.e.
tutorialSidebar: [{type: 'autogenerated', dirName: '.'}]

If, however, I use an autogenerated sidebar for that tutorial-basic sub-folder, such as

  tutorialSidebar: [
    'intro',
    {
      type: 'category',
      label: 'Tutorial Basics',
      items: [{type: 'autogenerated', dirName: 'tutorial-basics'}],
    },
  ],

then it will not use the link defined in the _category.json file of that sub-folder, meaning that the website will have Create a Page item in the sidebar, and clicking on Tutorial Basic item will just expand that category without opening the default page.

You said

A _category_.json works in joint with the actual autogenerated item, so the autogenerated item does respect what's in that file.

Are you saying that it was still supposed to use the link from the _category.json in the latter case?

[Josh-Cena]

So we improved the doc on this, hoping that it would clear up some confusion: https://docusaurus.io/docs/next/sidebar#autogenerated-sidebar-metadata

In your case, the items in tutorial-basics become a sidebar slice, with each file turning into an individual doc. The folder doesn't become a category. The _category_.json is only read when the current folder itself will become a category. It's not used to add metadata for the parent item. Autogenerated items never alter the behavior of the parent item.

[Josh-Cena]

So here, in order to stick to that principle that child items and parent item should be agnostic about each other, I believe the only choice is to allow you to exclude certain docs from the autogenerate folder. Sounds like a good resolution?

[XomegaNet]

Let me see if I understand the proposed resolution. Are you saying that if we add the link configuration to the sidebar.js then we'd also be able to configure it to exclude that default document from the sidebar, in order to mimic the behavior of autogenerated sidebars with the _category.json configuration?
In this case, yes, that would be great to have such an option.
Please feel free to reclassify it as an enhancement rather than a bug.

[Josh-Cena]

I'm saying that we should let you write

  tutorialSidebar: [
    'intro',
    {
      type: 'category',
      label: 'Tutorial Basics',
      items: [{type: 'autogenerated', dirName: 'tutorial-basics', exclude: ['create-a-page']}],
      link: {type: 'doc', id: 'create-a-page'},
    },
  ],

Because category doesn't know about what its subitem contains (well, it does, but it can't alter the subitems' behavior), and the autogenerated subitem doesn't know what doc the parent category uses. In this case you would have to explicitly tell the autogenerated item to exclude the doc that's already used as index page.

[XomegaNet]

Awesome, thanks. That was my understanding of your proposal as well.