Autogenerated sidebar items: allow more control on output

🚀 Feature

Several things:

• Add exclude option in category metadata to filter out docs;
• Add additionalItems option to include more items in autogenerated categories, including link, ref, etc.;
• Exclude entire subdirectories when declaring autogenerated sidebar items.

Have you read the Contributing Guidelines on issues?

Yes

Has this been requested on Canny?

No, but there are inline comments asking if they should be allowed, and the answer is yes: I’ve been asked about this feature.

Motivation

Sometimes we want a fully autogenerated sidebar, but occasionally want to add a few external links in categories. Sometimes we have a legacy directory structure and we only want to generate the sidebar from part of that directory.

API Design

In _category_.json, add the following options:

type CategoryMetadatasFile = {
  label?: string;
  position?: number;
  collapsed?: boolean;
  collapsible?: boolean;
  className?: string;
+ additionalItems?: WithPosition<SidebarItem>[];
+ exclude?: {
+   paths: string[];
+   docIDs?: string[];
+ };
};

paths accepts folder paths (I don’t know if file paths would work well; from my experience with the autogenerator code, seems it’s not easy since the doc metadata only includes sourceDir?), while docIDs accepts… doc IDs. It’s assumed that the members in these two arrays are otherwise included in the category; if they are never included (non-existent IDs/paths not in the autogen dir…), maybe throw an error, or maybe do nothing.

additionalItems accepts doc, ref, link, and even category, but not autogenerated (at least I think it doesn’t make much sense, and opens up holes to infinite recursion). Because doc items already come with their own sidebarPosition, they will be sorted well with the rest of the items. However, all items can have an additional sidebarPosition attribute (hence WithPosition<SidebarItem>) to override this behavior.

The autogenerated sidebar item will also accept the exclude and additionalItems properties, because the metadata file in the autogen dir root is not read.

Have you tried building it?

No

[slorber]

@lorenzolewis that looks like a similar case to https://github.com/facebook/docusaurus/pull/5830#issuecomment-1017146250 (except your doc is named index)

You should be able to do something like:

[
  {
    type: "category",
    label: "JS",
    link: {
      type: "doc",
      id: "index"
    },
    items: [
      {
        type: "autogenerated",
        dirName: "js",
        exclude: ["index"]
      }
    ]
  }
];

Eventually, we could figure a way to exclude it automatically, as it looks like a convenient default

We could also allow an include option so that you can generate the sidebar slice one level upper:

[
  {
    type: "autogenerated",
    dirName: ".",
    include: ["js"]
  }
];

Does it make sense?

[azinit]

Still actual!